¿Qué deberías dejar para tus sucesores?

Suponga que es un desarrollador exclusivo que deja un trabajo. ¿Qué tipo de información / material, fuera del código mismo, debe crear y dejar para su reemplazo?

Una respuesta obvia es "lo que quieras en un nuevo trabajo" con seguridad, pero ha pasado un tiempo desde que comencé un nuevo trabajo, y olvido cuáles eran las cosas más importantes que necesitaba en ese momento.

Estoy pensando:

• cuentas / contraseñas
• ubicación de equipos, copias de seguridad, CD de software

¿Qué más?

• Cuentas y contraseñas
• Información del servidor
• Buen código
• Documentación
  • Los diagramas y explicaciones de la base de datos son increíbles.
  • Lista de rarezas en el código
• Procedimientos
• Explicación de procesos manuales, o trabajos ocasionales, no obvios.
• Lista de programas que usaron o encontraron útiles
• Información del contacto ;)

Una fuerte taza de café y una nota de disculpa.

Es lo que desearía que me dejaran.

• Documentación. ¿Qué tan difícil es escribir algunos comentarios? Crear notas, notas de implementación, mover las notas del sistema. Qué hacer cuando reinicia y todo se ha ido.
• Documentos. Escribe por qué se está haciendo de esta manera, así que no tengo que preguntarme por qué no lo estás haciendo de otra manera. Cómo funciona el sistema de respaldo, cómo responde el servidor a cargas, pruebas, casos de prueba, casos de uso.
• Notas "Al usar la base de datos, nunca lo digas SELECT * FROM clients. No estamos seguros de por qué pero volca la base de datos" .

Mi dirección de correo electrónico, o tal vez incluso mi número de teléfono.

En mi experiencia, es difícil obtener cada detalle por escrito, por lo que lo mejor es estar disponible (hasta cierto punto) si sus sucesores necesitan más información.

Documentación de los programas que ha escrito, por ejemplo, su propósito, ubicación de los archivos de origen para el desarrollo futuro, contraseñas, etc.

Esto puede estar dentro del código como un comentario o afuera a simple vista.

Más que solo documentación, me gustaría saber por qué se tomaron ciertas decisiones cuando se tomaron. Actualmente estamos usando SWIG en un proyecto y uno de los otros desarrolladores quería saber por qué simplemente no usamos Boost :: Python. La respuesta simple era que el cliente no permitía el uso de Boost en ese momento. Ahora es una historia diferente.

Tales cosas los ayudarán no solo a comprender el proyecto, sino también a las limitaciones / limitaciones / desafíos que superó su implementación. Les dará un punto de partida para el mantenimiento futuro y el aumento de funciones.

Una cosa que no vi mencionar a nadie más (aunque podría haberlo pasado por alto) es documentar cómo configurar un entorno de desarrollo. Me doy cuenta de que la mayoría de las veces es solo instalar algunas cosas, obtener lo último, compilar y listo. Sin embargo, a veces hay más que eso (SharePoint es una situación que me viene a la mente) y documentar qué condensador de flujo debe configurarse de qué manera será muy útil para la pobre alma que lo sigue.

Si es un programa de escritorio, cómo construir todo el sistema desde cero (puede haber varios programas separados), cómo crear un paquete para distribución (qué dependencias tiene, por ejemplo, versiones de .NET) y cómo implementarlo en los servidores para descargar si corresponde, o grabarlo en un CD o DVD.

Si se trata de un programa basado en la web, FTP y (si corresponde) acceso SSH al servidor, y qué herramientas se utilizan para crear y probar el código localmente.

Si se trata de un sistema integrado, complete las instrucciones sobre cómo crear la imagen binaria, qué herramientas se utilizan, cómo descargar y actualizar el código en el producto, cómo configurar el sistema de archivos en el dispositivo, si corresponde.

Recientemente dejé un trabajo en circunstancias similares a las tuyas (no fui el único desarrollador, pero en realidad solo éramos dos, así que tenía bastante conocimiento de que el otro tipo no tenía (y viceversa, por supuesto)).

En términos de documentación normal, es importante documentar una descripción general de todo el sistema. Los componentes individuales ya están documentados en el código, pero la interacción entre los componentes y por qué esto hace eso o por qué esto necesita hablar con ese componente es importante y no siempre es fácil de resolver simplemente depurando / mirando el código.

Luego, durante aproximadamente un mes antes de irme, cada vez que hacía algo que solo yo podía hacer, escribía exactamente lo que sucedió, lo que tenía que hacer y por qué. Esto solía ser un caso de "había un error en el componente xyz, para solucionarlo supe que debía buscar en el archivo abc debido a X, luego tuve que hacer esto, esto y esto".

Por supuesto, dejé mi dirección de correo electrónico y número de teléfono en caso de que surgiera algo que no pudieran resolver por su cuenta. Recibí algunas llamadas en las primeras semanas, pero lentamente se fueron.

A todos nos gustaría un diagrama de flujo de datos completo del sistema con una lista de requisitos funcionales. ¡Lo más probable es que nunca lo hayas escrito cuando escribiste el sistema en primer lugar! Como en la mayoría de los lugares, la mejor documentación es probablemente el código en sí, por lo que lo que más me gustaría es un código bien documentado. Líneas y líneas de comentarios en el código que explican lo que está tratando de hacer tanto técnica como funcionalmente.

La regla # 1 para la documentación no es lo que hace sino por qué . ¿Cuál es la historia de fondo de los programas que se ejecutan y qué hacen?

Creo que lo que me encantaría ver en las documentaciones, además de lo habitual, sería qué características quedaron fuera. Por ejemplo, por qué NO se implementaron ciertas ideas o NO se usó una determinada plataforma o método (que de otro modo era una opción obvia).

Esto asegura que el sucesor siempre sepa qué no hacer o si es más capaz, entonces tal vez pueda idear una solución y hacer que ciertas funciones funcionen.

Esto es especialmente aplicable a proyectos de código abierto. ¡Puede ahorrar mucho tiempo y poder mental!