Documente el diablo de todo.
Recientemente hubo un hilo en Slashdot sobre el inicio de la documentación, lo que me inspiró a escribir mis pensamientos sobre la documentación.
Mis puntos clave fueron:
Principio # 1: nunca se hace
La documentación es un esfuerzo continuo que siempre va a la zaga de lo que está en producción. Los cambios se hacen ad-hoc, las cosas se mueven o se suspenden o se ponen en servicio al azar. La documentación nunca se pondrá al día.
Debe vender a las personas que pagan las facturas sobre el valor de pasar tiempo (y, por lo tanto, dinero) para mantener actualizada la documentación en ejecución. Con frecuencia esas conversaciones son así: "¿Recuerdas cuando tuve que gastar $ TIME para descubrir cómo $ THING se rompió? tengo que resolverlo todo ".
Tienes que hacerlo, aunque nunca terminarás.
Principio # 2: Lo único peor que no tener documentación es documentación incorrecta
Esto es más una obviedad que un principio. La documentación puede llevarlo a la falsa sensación de que algo está en un estado conocido y que, si algo sale mal, puede comenzar a solucionarlo.
Es importante reconocer este problema.
Principio # 3: está escribiendo documentación para su sucesor
Las probabilidades son el 95% de cualquier documento que documente al que nunca tendrá que volver a consultar. La documentación es una colección de sabiduría para el futuro, no para ti. Por lo tanto, debe suponer que su audiencia sabe poco o nada acerca de los detalles de cómo son las cosas como son.
Y habrá un sucesor. No sé sobre ti, pero no planeo estar en estos entornos específicos por el resto de mi vida. Las oportunidades van y vienen, y cuando vienen, a veces tú vas. Pero la vida sigue detrás de ti, y cuanto más suave puedas hacer la vida para tu sucesor, mejor. De lo contrario, podría tener una colección de antiguos clientes que dicen en voz baja cosas poco halagadoras sobre usted. Me gusta decir que son los mismos 50 muchachos que trabajan en todo el mundo en TI en Ottawa porque te los encuentras en todas partes. Ayudar a su sucesor podría abrirle puertas en el futuro.
Ahora, hasta cierto punto, siempre hay un grado de "culpar al tipo anterior" cuando surgen problemas. Eso es parte del negocio. Lo hice yo mismo. Pero en varias ocasiones cuando había criticado al tipo anterior como una especie de imbécil, aprendí lo contrario que él realmente actuaba juntos y sabía más sobre lo que estaba sucediendo que yo en ese momento.
Principio # 4: "Por qué" es a menudo más importante que "Cómo"
Cuando miramos un sistema, la mayoría de nosotros comienza a pensar, ¿por qué demonios es así? Casi siempre hay razones muy específicas para las elecciones de configuración realizadas. En estas circunstancias, el "Por qué" dicta el "Cómo", y debe asegurarse de que el lector comprenda los problemas específicos que se resuelven al examinar los restos de fumar de su solución.
Principio # 5: Tiene que ser fácil o no lo harás
Esto significa que debe ser muy consciente de sus herramientas, así como de aquellos que las utilizarán.
Mantener las cosas actualizadas debe ser fácil. Si tiene que hacer algún tipo de esfuerzo, encontrará excusas para evitar hacerlo cuando sea mejor hacerlo, que es inmediatamente después de un cambio.
Si sus herramientas no son fáciles de usar para otros, entonces no las usarán. Esto puede ser especialmente paralizante en un entorno de equipo, ya que cuanto más grande sea el equipo, más probabilidades hay de que encuentres un miembro del equipo al que no le guste tu elección de herramientas.
Personalmente, me gusta un wiki para documentos. Sin embargo, el problema es que un wiki no te impone una estructura, por lo que la estructura debe imponerse desde afuera. Esto siempre conduce a un conflicto en alguna parte ya que alguien más tiene una idea mejor / diferente.
En algunos lugares he usado documentos de Word y Visio "publicados" en PDF, y el "último" PDF se considera autorizado. Esto es bueno porque luego tiene una colección que puede entregar a su empleador / sucesor. Los archivos PDF, si están correctamente fechados, pueden proporcionar un registro histórico de lo que sucedió, aunque no es fácil de navegar. Es malo porque no me gusta Word o Visio y me he visto obligado a obtener una comprensión básica de estas herramientas para comunicar las ideas de manera efectiva.
Mi empleador actual está jugando con la idea de documentos de Word en un portal de Sharepoint. Solo tendremos que ver qué tan lejos llegamos allí