¿Cómo escribo la documentación técnica de traspaso antes de dejar una empresa?

Estoy cumpliendo preaviso en mi organización, y un jefe de proyecto me ha pedido que escriba un documento sobre lo que he hecho. He mencionado brevemente los puntos en los que he trabajado, pero no he hecho ningún análisis "in-code". No está satisfecho con el documento, dice

La persona que se hace cargo debe ser capaz de entender lo que hizo usted teórica y técnicamente.

¿Cuál debería ser mi enfoque hacia él?

Si comenzara un trabajo y alguien le diera viñetas sin un recorrido por ninguno de los sistemas, la arquitectura y la implementación, ¿cómo se sentiría? Debe brindarle a alguien el tipo de información que le gustaría ver si fuera admitido en una nueva organización. Necesitará profundizar mucho más que unos pocos puntos.
@JaneS Me sentiría como un día normal en otro sistema existente sin documentación :). Sin embargo, creo que el gerente del proyecto debe establecer un objetivo sobre lo que debe estar en la documentación. OP podría escribir mucho, pero está en período de aviso, por lo que es mejor centrarse en contenido menos pero más relevante y asegurarse de que se valide.
Preguntar cómo escribir documentación técnica parece estar más allá del alcance de este sitio, y esta pregunta parece demasiado amplia. ¿Por qué no le preguntas a tu PM qué espera? ¿Qué es lo peor que puede pasar? Ya estás en tu período de preaviso.
@gnat No es un duplicado. La pregunta vinculada pregunta si están obligados a escribir un documento o no. Esta pregunta es cómo escribir correctamente un documento.
En resumen: lo mejor que puedas en el tiempo disponible. Esto es probablemente iterativo ya que estimar el tiempo es complicado. Entonces, las viñetas son un buen comienzo, pero deberían terminar siendo encabezados de sección. Y el trasfondo siempre es importante, con nombres de personas clave (con respeto por supuesto)
¿Por qué no haces más preguntas y obtienes aclaraciones? Tal vez tengan un ejemplo del trabajo de otra persona que anteriormente dejó la empresa.
Cualquier documentación es mejor que nada, pero un trabajo apresurado para documentar algo es solo un poco mejor que nada. Los documentos deben escribirse a medida que se realiza el trabajo, no en su último día. Su gerente no lo ha manejado lo mejor posible.

Respuestas (6)

Está escribiendo lo que se conoce como "Documentación de traspaso". El objetivo de esta documentación es transmitir el conocimiento de cómo funciona este software y cómo se escribe, mantiene e implementa a las personas que lo seguirán.

Hay una pregunta/respuesta relacionada en Stack Overflow que generalmente cubre los temas que debe abordar en su propio documento:

¿Cuáles son los elementos básicos que se deben incluir en la documentación de soporte?

Citado en parte:

• La documentación del código (javadoc, doxygen, etc.)
• Detalles sobre el proceso de compilación
• Dónde obtener la fuente actual
• Cómo archivar errores (sucederán)
• Ruta para proporcionar parches a la fuente o a los clientes

• Cómo funciona (simple, pero a menudo se pasa por alto)
• Partes personalizables por el usuario (p. ej., hay un componente de secuencias de comandos)
• Contactos principales para cada componente, también conocido como ruta de escalamiento
• Fomento de los comentarios de Soporte sobre qué más quieren ver

Considere también:

  • Se requieren credenciales del sistema/usuario (¡no incluya las contraseñas en la documentación!)
  • Donde están los servidores dev/test/UAT/database/cualquier otro servidor asociado
  • Dónde está el servidor de producción
  • Pasos de implementación
  • Si hay alguna licencia involucrada
  • Ubicación de los requisitos originales/documentos de análisis para cada pieza de trabajo

Buscar en Google "Documentación de traspaso" también le dará más información.

Para ahorrar tiempo, escribiría una serie de viñetas (como las anteriores y de su propia investigación de acuerdo con este proyecto) y se las presentaría a su PM. Pídale que marque las que quiere ver y que agregue otras que considere apropiadas.

Conseguir que el PM marque lo que quiere es un gran ideal. Aunque corres el riesgo de que diga "¡Todo! ¡Ayer!" :-D
Esto puede depender de las limitaciones de tiempo; algunas cosas pueden ser más importantes que otras. Es posible que ya haya documentación para cubrir algunos de esos encabezados también.
A pesar de lo que pueda pensar el gerente, generalmente el primer punto (documentación del código) es, con mucho, el menos importante. Cuando necesita la fuente, no puede adivinar dónde conseguirla o cuál tomar. O lo sabes o no lo sabes. Las construcciones a veces también son extremadamente complicadas. El código (si no es terrible) debería ser legible de todos modos.
Como PM yo mismo, el 90% de las cosas que enumeró espero haber sido escritas por mí mismo como PM.

Voy a adoptar un punto de vista un poco cínico, de abogado del diablo...

La respuesta de Snow enumera una gran cantidad de cosas buenas que deben documentarse, pero casi todo esto ya debería estar documentado y mantenerse actualizado continuamente. Si esta documentación no existe (y sé que habrá muchos lugares donde no existe), entonces eso es esencialmente una falla de su administración al no implementar las prácticas correctas durante su tiempo en la empresa. Si ese es el caso, no es bueno que traten de remediar su fracaso "descargándose" en la persona que deja la responsabilidad de "documentar todo".

La respuesta de Kilisi sugiere " Hazlo como te gustaría leerlo si estuvieras tomando el control ", lo que nuevamente es un buen ideal, pero quizás debería moderarse con la consideración de lo que te dieron el primer día. Si le dieron casi nada, por ejemplo: " Ahí está el código, si no puede averiguar cómo funciona algo, pregúntele a alguien ", y la situación no ha cambiado desde que comenzó, de nuevo, no es realmente la responsabilidad de la persona que se va a arreglar las malas prácticas.

La esencia de lo que estoy tratando de decir es: si se aplica, no se deje intimidar para tratar de corregir las malas prácticas inherentes .

  • Si la mayoría de las cosas ya están documentadas con buen detalle, su "entrega" debería ser relativamente corta; el puñado de cosas "en tu cabeza" de las que otros podrían no ser plenamente conscientes. Usted sabrá mejor cuáles son, pero debe buscar orientación de su gerente de proyecto sobre cualquier área específica en la que esté interesado.

  • Si la documentación existente es escasa, está desactualizada o no existe, entonces no es su responsabilidad corregir la "falla sistémica" cuando se vaya. Haz una descarga de cerebros lo que puedas, para ayudar al pobre diablo que te reemplaza, pero no te sientas culpable porque esta situación debería haber sido abordada (por la gerencia) hace mucho tiempo.

Por supuesto, si ha "acumulado" deliberadamente información que solo usted conoce y no ha mantenido actualizada la documentación existente, entonces debería ser su responsabilidad pasar finalmente esa información de la manera más útil posible. !

Estoy de acuerdo en que no es práctico arreglarlo en su último día, pero estoy totalmente en desacuerdo con que dependiera de la "administración" obtener la documentación durante su tiempo en la empresa. Es su responsabilidad personal documentar datos cruciales sobre su trabajo mientras está en el trabajo, ya sea que la gerencia lo diga o no, al igual que es su responsabilidad personal hacer un buen trabajo en primer lugar. Es una cuestión de ética, no de moral.
@Comodín. Es una responsabilidad conjunta. Sí, un programador debería documentarlo todo, pero también sabemos que muchos de ellos preferirían continuar con el siguiente trabajo "real". La gerencia puede ayudar haciendo que el proceso sea lo menos doloroso posible, alentando una cultura que lo desee y reforzándola cuando sea necesario.
@TripeHound ... sin mencionar que la documentación es lo primero que se debe hacer cuando las cosas se ponen difíciles. Cuando hay que elegir entre cumplir con la fecha límite o mantenerse dentro del presupuesto y hacer la documentación, la documentación se queda en el camino cada vez, y eso generalmente depende de la dirección de la gerencia, no porque así lo quieran los recursos técnicos.
@ HopelessN00b Cierto. Y el objetivo principal de mi respuesta es si , por cualquier razón, de quién sea la "culpa", una empresa se encuentra "infradocumentada", esperar que alguien se vaya para "arreglar" las cosas mágicamente no es razonable. Otras respuestas cubren muy bien qué hacer si todo es como debería ser.
@TripeHound estamos completamente de acuerdo.
comprar "dumping" -> por "dumping"

¿Cuál debería ser mi enfoque hacia él?

Hazlo como te gustaría leerlo si estuvieras tomando el control. Aparte de eso, solo envíe su aviso y concéntrese en hacia dónde se dirige su carrera. A menos que su jefe le esté dando un formato a seguir, no hay mucho más que pueda hacer con lo que esté completamente satisfecho.

Normalmente hago un recorrido paso a paso de todas mis tareas, asumiendo que debe ser seguido por un principiante. Así que sin abreviaturas, sin jerga, etc.

Lo más importante que me gustaría saber cuando tomo el relevo de otro desarrollador es el común "qué, por qué, cómo" del proyecto. Eso es:

  • ¿Qué es? ¿Qué hace?

  • ¿Por qué elegiste hacer las cosas de cierta manera? Siempre me preguntaré por qué un desarrollador se decidió por un determinado marco o idioma y el contexto o la advertencia sobre ciertas cosas que no había considerado son invaluables.

  • ¿Cómo resuelve el proyecto los problemas enumerados?

La otra cosa más importante es obtener una máquina nueva, que no tenga nada que ver con el proyecto e intentar llegar a una configuración que funcione (tal como tendrán que hacer cuando se hagan cargo).

No tienes idea de cuántas veces le he preguntado a un ex-desarrollador de proyecto por qué su documentación no funcionó y me dirán: "Oooh, sí, solo necesitas agregar esta variable de entorno, lo había olvidado". Es normal y humano no tener en cuenta cada paso en una instalación, pero hará la vida mucho más fácil en el próximo desarrollador dado que ahora tiene la mentalidad correcta.

Imagínese que está haciendo una transferencia de conocimiento con otro desarrollador que continuará donde lo dejó. Normalmente, revisaría el código a un alto nivel y mencionaría cualquier cosa de interés, puntos débiles particulares, lugares que a menudo tienen errores, etc. Esto le dará puntos de partida para crear la documentación.

Dado que este es un documento escrito y el siguiente empleado no podrá hacer preguntas, es posible que desee ser más explícito de lo que sería al dar una descripción general verbal.

¿La persona que se hace cargo de sus tareas ya está trabajando para la empresa o tendrá alguna coincidencia con usted?

Si es así, deje que esa persona revise la documentación si es lo suficientemente buena para él/ella. (O si tiene un colega que pueda ayudarlo). Es imposible cubrir todo, así que concéntrese en las cosas difíciles, las cosas raras, las excepciones a los estándares de la industria, etc.

Y sé que es aburrido y probablemente mentalmente ya te hayas ido de la empresa. Y dependiendo de por qué te fuiste más o menos fiel a la empresa. Pero sugiero trabajar de manera iterativa para que tenga objetivos más cortos y solicite comentarios con frecuencia. Dado que le queda un tiempo limitado y la empresa debe utilizarlo de la manera más eficiente posible, escribir documentación innecesaria es un desperdicio y es posible que se pierdan las cosas importantes.

¿Cómo escribo la documentación técnica de traspaso antes de dejar una empresa?
RespuestasAquíPolítica de privacidad1y, 1v