APEX 02.03 - Cosa Numero 2 de 10 - La Documentación Técnica

 “Nunca olvidaré porqué estoy escribiendo este fragmento de código”, estos son dichos que decimos como desarrolladores a lo largo de la historia para justificarnos y después de tratar de resolver el problema durante horas. Y es posible que realmente creas que estás diciendo la verdad, pero, hazme caso..

LO VAS A OLVIDAR

Incluso, podrías encontrarte años después mirando ese código y preguntándote qué tonto podría haber escrito algo tan intrincado, antes de darte cuenta que oppps. ese fui yo…😬

La documentación técnica es fundamental en cualquier proyecto de desarrollo de software.

La documentación proporciona una hoja de ruta para los desarrolladores que describe cómo debería funcionar el sistema y qué hace cada componente. Además, puede ser utilizado como referencia por los usuarios que necesitan comprender cómo funciona el sistema o solucionar problemas. 

La documentación ayuda a garantizar que todas las partes interesadas tengan una comprensión común del sistema, lo que evita malos entendidos costosos en el futuro. Asegurarse de tener un proceso o estándar para la documentación es clave en el éxito a largo plazo de tus proyectos.

¿Y estos 20 ítems en tu lista de requerimientos?, pues déjalos por ahora y documenta rápidamente ese fragmento de código inteligente que has creado. Tú y tus futuros colegas te lo agradecerán.

Algunos consejos con relación a la documentación:

• Escribe cuando todavía esté fresco en tu mente. ¡No hay tiempo como el presente!
• Documenta tus cambios de código
• Mantenlo simple. No todas las líneas necesitan documentación
• Crea un documento de inicio rápido para todos los activos claves del proyecto: enlaces a entornos, repositorios de código, tableros, etc. Esto ayuda a incorporar a los nuevos miembros del equipo de manera eficiente
• Mantén la documentación de forma a que sea fácil de encontrar
• Evita los tecnicismos, la documentación debe ser fácil de entende

La documentación debe ser práctica, sencilla y no te debe llevar mucho tiempo hacerla, encuentra tu equilibrio.

Creditos: Esta serie se ha basada en la publicación de INSUM, adaptada del ingles y con mis contribuciones adicionales. Puedes ver la publicación original aqui: https://www.insum.ca/10-things-to-include-in-your-next-oracle-apex-project/

Siguiente Artículo: APEX 02.04 Cosa Número 3 de 10 - El Control del Código Fuente

¿ Estas interesado en contactarnos ? envianos un mail a contacto@softsanluis.com con un breve comentario de lo que deseas y con gusto un responsable se comunicará contigo.

Juntos, creamos las aplicaciones del futuro!

Mi nombre es José Preda.

* José es Analista de Sistemas e Ingeniero de Software con especializaciones en tecnologías de Oracle, Microsoft, redes, infraestructura tecnológica y gestion de recursos humanos. Posee mas de 30 años de experiencia en el área de tecnología, es de Paraguay, vive y trabaja en San Luis, Argentina. Fue consultor, capacitador y soporte técnico para Oracle, se ha desempeñado en el ámbito privado como Gerente de Proyectos para el Grupo Relcat y como consultor experto para el Gobierno de la Provincia de San Luis, desde el año 2013 es miembro activo y Coordinador Regional del Grupo de Usuarios Oracle de Argentina del cual es miembro del directorio desde 2023. En el año 2017 fundó Consultora Soft San Luis, una startup especializada en brindar formación profesional, consultoria, mentoria y soluciones con tecnologia Oracle y Oracle APEX a empresas, equipos de desarrollo de consultoras y a particulares.