En mi opinión (desde la perspectiva de un desarrollador de software), hay cuatro niveles de documentación:
- Comentarios dentro del código fuente.
- Documentación de interfaz.
- Documentación del sistema.
- Documentación del usuario.
Mis dos centavos por cada uno:
- Use solo donde tenga que hacerlo. La necesidad de dicha documentación es a menudo un síntoma de código que no está estructurado para simplificar. Sin embargo, a veces hay buenas razones para seguir con código complejo (rendimiento, por ejemplo).
- Más es mejor, pero no pierdas el tiempo: por lo general, trazo la línea en la documentación de los privados. Siga las prácticas comunes de su plataforma / idioma.
- Escriba una buena documentación general del sistema (tal vez solo un readme.txt de inicio). Manténgalo cerca del código fuente: le sugiero que marque o reestructure el texto en el repositorio. ¡Actualice siempre con cualquier cambio! Manténgalo lo suficientemente corto como para leerlo en una hora o menos.
- Esto no es algo en lo que los desarrolladores de software sean generalmente buenos, pero los escritores técnicos sí lo son. Ayude a su escritor técnico pero no intente hacer su trabajo.
- ¿Por qué UML todavía está en cursos en entornos académicos? ¿Cuál es el futuro de este lenguaje?
- ¿Cuál es la tarifa por hora para un ingeniero de software?
- ¿Cuál es el precio de desarrollar un software complejo de administración de la empresa (servidor, integración de mapas, Android + Windows)?
- ¿Cuál es la diferencia entre informática, ingeniería informática e ingeniería de software? ¿Cómo es el alcance de TI en comparación con SE o CS? ¿Es la informática una buena opción para especializarse en el desarrollo de aplicaciones móviles?
- ¿La mayoría de los buenos programadores tienen cierto tipo de personalidad? ¿O es su personalidad independiente de su habilidad de programación?