¿Cómo puedo documentar el trabajo pasado de otra persona? [cerrado]

Estamos en una mala situación de tener muy poca documentación sobre la personalización que nuestros trabajadores anteriores hicieron a un sistema crítico del negocio. Se realizaron muchos cambios en Crystal Reports, entidades de bases de datos y archivos de configuración / programación patentados para nuestro software ERP.

La documentación actual generalmente lee algo como esto:

Este programa se ejecuta antes de facturar. Errores conocidos: ninguno.

Ejecute este programa después de instalar el software X.

Cambió los siguientes campos en este informe: (sin explicación de cómo o por qué)

Nuestra tienda de TI es pequeña, y en el caso del software ERP, la mayor parte del trabajo se concentró en una persona (ese soy yo ahora), por lo que nadie más aquí sabe lo que hicimos. El departamento de TI y contabilidad conoce partes y piezas (ocasionalmente muy útiles) pero no es suficiente.

Otro problema es que nuestro departamento de contabilidad parece pensar que estamos bien documentados. Es cierto que guardamos muchos registros de lo que salió mal , pero muy poco explica qué se hizo (si acaso) para solucionar estos problemas. Tenemos cientos de documentos que explican errores, pero los documentos que explican los cambios (como se muestra arriba) son casi inútiles.

¿Cómo puedo documentar los cambios pasados ​​cuando no sé qué se hizo? Puedo comenzar documentando lo que hemos cambiado: archivos, tablas de bases de datos, etc. que necesitamos para que el sistema funcione. También puedo documentar lo que hacemos ; cuando se ejecutan los informes, por qué se les dijo a las personas que usaran el informe / programa X. Pero cuando una de estas cosas personalizadas tiene un problema, siempre vuelvo al punto de partida.

¿Cómo puedo documentar proactivamente estas cosas para mí y para otros?

Creo que este es un ejercicio inútil. Si funciona, funciona, si no funciona, tienes que arreglarlo.

La mejor manera de documentar cosas viejas es mientras trabaja en ellas, documentar lo que está haciendo y explicar la lógica de negocios (que supongo que no fue documentada). Esto será de gran ayuda para cualquier desarrollador nuevo.

Hablando de documentar código / cosas viejas, alguien tenía que ser el dueño. Supongamos que este es su gerente actual. Es posible que él / ella no tenga un conocimiento técnico completo, pero sabrá qué cambios se hicieron. En ese caso, no es tu trabajo. Puede ser que el gerente pueda escribir algo al respecto sobre los cambios realizados. Sería útil mantenerlo como historia. Si surge un problema como ese, puede profundizar en esas áreas, eso podría ser muy útil para usted. Pero entrar en el código y documentar los cambios es bastante inútil IMO y probablemente imposible.

Abandone su esfuerzo para documentar los cambios .

En cambio, comience a documentar qué funciona actualmente y cómo . Mantenga esa documentación actualizada y actualizada a medida que realice cambios en el futuro.

¿Tienes control de fuente?

¿Puedes averiguar qué ha cambiado a partir de eso?

Si es así, entonces puede asignar eso a los cambios comerciales, ya sean nuevas características o correcciones de errores.

¿Es posible resucitar un antiguo buzón de desarrolladores? (No estoy seguro si esto es viable con preocupaciones de privacidad o no). Es posible que se obtenga mucha información al rastrear por allí.

Lo primero es lo primero. ¿Dónde guarda su documentación? Si aún no lo ha hecho, configure un wiki. Prefiero dokuwiki yo mismo, e incluso hay una vm precompilada , si estás tan inclinado.

Esto proporciona algunas características importantes:

• Se puede acceder a los documentos desde cualquier lugar de la LAN de la empresa (instalación en una computadora nueva ...)
• Todos los documentos están en un solo lugar.
• Todos los documentos se pueden buscar
• Puedes colaborar (nuevo colega, usuarios del software)

Ahora, si su documentación está en papel, le deseo lo mejor. Si tiene documentos de Word, cree un script de importación .

Finalmente, solo usa las cosas . Siempre que necesites instalar algo, pon notas en la wiki. Si tocas un caso de borde, ponlo en la wiki. Aquí es donde la colaboración puede brillar, ya que haces que otras personas hagan el trabajo por ti.

Pasando a una documentación más específica, si necesita trabajar con la fuente para varios proyectos, ¡ asegúrese de tener un entorno de desarrollo adecuado configurado ! Para una lista de verificación de cosas que debe tener:

• Control de versiones ( git , mercurial , fósil )
• Seguimiento de errores ( trac , mantis , redmine , fósil )
• Sistema de compilación ( autotools , scons , buildbot )
• Control del proyecto ( eclipse , estructura de directorios especificada, complemento del editor )
• Documentación de origen (README, TODO, INSTALL, comentarios de origen)

Finalmente, debido a que la documentación puede ser aburrida, conviértela en un juego. Dése "puntos" para cada elemento en su lista de verificación, revisando periódicamente su "puntaje". Es una buena manera de ver lo que has logrado y qué tan bien. También te indica dónde debes ir a continuación.

Mire esto como una oportunidad para aprender muchas cosas sobre cómo configurar un entorno de desarrollo adecuado, y no tenga miedo de probar cosas y seguir adelante. Encuentre algo que le guste y migre el entorno para que las cosas mejoren . Enfoque esto como un proyecto en el que busca construir la mejor solución.

Editar:

Según el comentario de la plataforma a continuación, otra cosa útil para hacer es crear diagramas del código fuente. Freecode tiene cosas , y este artículo enumera algunos de los idiomas populares.

Lo mejor que puede hacer es documentar todo lo que sabe y pedirle a la compañía que documente cualquier cosa que otros también sepan. Sugiero centralizar la documentación en una wiki o algo similar para que todos tengan acceso a la documentación más actualizada.

No puede documentar algo que no sabe, por lo que intenta aprender y descubrir por qué se hizo algo o simplemente lo deja sin documentar. Esta es la razón por la cual la compañía necesita tener mayor cuidado para documentar las cosas, mientras que los que saben todavía están empleados allí.

Si está intentando documentar cualquier código que no entienda, le sugiero que escriba pruebas unitarias para probar la funcionalidad. De esta manera, comprenderá mejor lo que hace el código y las pruebas en sí mismas pueden servir como documentación.

¡Buena suerte!

Cuando trato de documentar algo que otra persona que ya no está con el proyecto o la compañía hizo, siempre comienzo la actitud de: Esta es una caja negra para todos, incluyéndome a mí, hasta que necesite cambiar algo o explicárselo a otra persona.

La razón por la que este proyecto está en la forma de documentación en la que lo ha encontrado es porque la documentación de cualquier trabajo es algo secundario para que se ejecute. Así que documente lo que cambia y si ha descubierto cuál es el campo en particular en la base de datos y qué bloque de código en particular hace, si para el beneficio de nadie más que del suyo.

Podrías escribir pruebas exploratorias automatizadas. Estos tienen varias ventajas:

• Aprendes cómo funciona el sistema a medida que los escribes

• Sirven como documentación ejecutable para más tarde

• Si los ejecuta de forma regular o incluso continua, brindan una buena red de seguridad para detectar cuándo los cambios rompen algo o cuándo deben actualizarse

Sin embargo, no sé si es factible escribir ese tipo de pruebas en su entorno particular.