Documentación

Documentación

¿Qué documentar?

• Como implementar nueva funcionalidad.
• Como se realizan las pruebas.

Lo mínimo que necesita las personas que quieren colaborar o heredar tu proyecto.

¿Como documentar?

• UML como documentación.

¿Dónde documentar?

• Propio código.
• Sistema de documentación.

• Wiki
• Ficheros externos.
• README

¿Cuándo documentar?

• Documentar inmediatamente después de codear.
• Cuando se resuelve un problema, documentar la solución.

Documentación

Una buena práctica cuando se trabaja en equipo es documentar. Se trata de dejar por escrito las decisiones que hemos tomado, como está funcionando el código, etc.

¿Qué documentar?

• El estado de nuestro código para que se puede implementar nuevas funcionalidades a futuro.

¿Cómo documentar?

• ¿Quiénes van a leer nuestra documentación?
• ¿Cuál el perfil de nuestra audiencia?

¿Dónde documentar?

• En nuestro código
• Otro repositorio externo, algo tipo Notion o una página web como Atlanssian.

¿Cuándo documentar?

• Lo ideal es escribirla mientras el código se va desarrollando.

sin embargo cuando se hace desarrollo web, dentro del html/javascript/css no es recomedable tener cosas comentadas ya que primero revela información que no debería tener el usuario y segundo queda desprolijo. Simplemente con el inspector de código del navegador se podría ver todo eso

Un lugar donde se puede tener la documentación es en un README de nuestros repositorios en GitHub.
Puedes aprender a cómo escribir unos buenos README’s en éste enlace 😉

La documentación en el código me encanta, cuando descubrí que VS Code tomaba la descripción de esos comentarios empecé a usarlos, pero claro, hay que respetar el formato mostrado para que funcione, sin duda la documentación en la mejor manera de entender qué hace el código:D!

Para GitHub pueden crear su documentación de sus repositorios en la sección “Wiki”, comparto este vídeo al respecto: https://www.youtube.com/watch?v=RhydZnn7Zqc

Aunque un buen archivo README siempre es importante para encontrarse con la información necesaria a primera vista, para editar y agregar distintos elementos al README comparto ese sitio / editor: https://pandao.github.io/editor.md/en.html

La documentación debe hacerse pensando en quien la va a leer.

Una buena documentación ofrece:

• Garantías de un producto final de la mayor calidad.
• Pensar en el futuro.
• La confianza de que se determina el mejor proceso para desarrollar su producto.

Buenas prácticas

Pull Request al momento de realizar una contribución a la rama principal

Documentación

Es lo mejor que podemos de hacer para el siguiente desarrollador que coja el código que nosotros dejamos o para quienes quieran aportar al código.

Existen varios tipos de documentación y todos igual de importantes. La documentación dentro del código, la documentación escrita acerca del proceso y la lógica del programa y la documentación visual.

¿Cuándo documentar?

Lo ideal sería hacerlo mediante se realiza el código. Sin embargo, no siempre se puede hacer a la par del código pero siempre es importante hacerlo.

🍃 Documentar es una de las mejores prácticas que podemos hacer cuando estamos en un equipo de trabajo. Dejar por escrito cómo hemos hecho algunas funcionalidades, cómo podría ser mejorado el código y por sobre todo debemos dejar comentarios en el código que ayuden a las personas a ubicarse en qué parte de la aplicación están y qué hacen esas líneas de código.

Además de ayudar a las personas a ubicarse en el código y entender su funcionalidad, la documentación de código también tiene otros beneficios. Por ejemplo, puede facilitar el proceso de depuración de errores ya que permite a los desarrolladores rastrear y solucionar problemas más rápidamente. Asimismo, la documentación puede ser útil para futuros miembros del equipo que se unan al proyecto, ya que les permite comprender rápidamente cómo funciona el código y qué decisiones de diseño se tomaron en el pasado. En general, la documentación es una herramienta valiosa para mejorar la calidad del código y la eficiencia del equipo de desarrollo.

Unified modeling language

El UML (Lenguaje de Modelado Unificado) es una herramienta de modelado visual que se utiliza para describir y diseñar sistemas de software. Se utiliza para representar los diferentes aspectos de un sistema, incluyendo su estructura, comportamiento y arquitectura. El UML consta de varios tipos de diagramas, como diagramas de caso de uso, diagramas de clases, diagramas de secuencia y diagramas de estado, que se utilizan para representar diferentes aspectos del sistema. Cada tipo de diagrama se utiliza para modelar un aspecto diferente del sistema y proporciona información valiosa para los desarrolladores y otros miembros del equipo de desarrollo de software.

Herramientas de documentación

Existen diversas herramientas para la documentación de código, algunas de ellas son:

• Doxygen
• Javadoc
• Sphinx
• Gitbook
• Read the Docs

Estas herramientas te permiten generar documentación a partir del código fuente y facilitan la tarea de mantener actualizada la documentación.

Guía de sintaxis para documentar en el mismo código (específicamente para PHP):
https://docs.phpdoc.org/guide/references/phpdoc/basic-syntax.html#basic-syntax

Con que esta es la famosa documentación de los memes Devs que nadie realiza… Pensé que era más complejo, es decir, casi casi un manual del código.

No se ve tan difícil o sí?

Estos cursos les puede ayudar:
Curso de Programación Orientada a Objetos: POO
Curso de Introducción al Technical Writing y Documentación de Código

Que cosa del mal el código con malos identificadores y sin comentarios 😣

Gracias por este completo curso Mauro!

Todo clarísimo. gracias

A tomar buenas costumbres documentando.

Sirve bastante cuando se implementa una nueva funcionalidad que dependa de un feature flag.

Mi proceso para desarrollar código es que primero comento, luego documento y por último codifico o programo

Les recomiendo ver el curso de CodeStream, les comparto el enlace https://platzi.com/clases/comunicacion-codestream/

Resumen Clase: la documentación es otra buena practica de escritura de código limpio y mas cuando se trabaja en equipo. Dejar por escrito las decisiones que hemos tomado, como funciona el código entre otras cosas. Que debemos de documentar tomando en cuenta a las personas que vendrán después de uno o de nuevos trabajadores. Por ejemplo que documentar, como se realizan las pruebas,quienes son los involucrados en el proyecto, como implementar una nueva funciones y como hacerlo, como implementar el código en producción, la segunda pregunta es como documentar, la respuesta es quien va a leer la información, el lenguaje a utilizar depende a quien va la documentación, en la documentación también debe de incluir imágenes y esquemas para dar mejor entendimiento. Donde documentar, dos lugares por ejemplo dentro del mismo código o dentro de otro repositorio, en la web o donde nos convenga como programadores. Cuando documentar lo ideal es escribir la documentación cuando terminamos una funcionalidad, cuando finalmente se resuelven problemas complejos y te faltaba información y conviene documentar lo nuevo.

Recomiendo de sobre manera Notion para documentar.

http://www.umlzone.com/

Inicia tu proceso de documentar pensando en:

• Que necesita este wey para seguir trabajando en el código tal como esta.
• Quienes son los involucrados en el proyecto
• Cómo puedo implementar nuevas funcionalidades.
• Cómo se hacen las pruebas.
• Cómo se lleva a producción.

Puedes documentar tu código en VS Code poniendo:
/**
TITULO DE LA FUNCION
@param PARAMETRO1 FUNCION
@param PARAMETRO2 FUNCION
@param PARAMETRO3 FUNCION
**/

Es bueno tener también los enlace de las soluciones que encontramos, esto puede ser útil para cuando regresemos y ver de dónde y porqué fue que se dio esa solución. O tener una guía más amplia de lo que nos ayudo a resolver el caso.

Documentacion

Es una buena practica dejar por escrito las decisiones que se han tomado, como esta funcionando el codigo, entre otros.

Que documentar? Pensando en la persona que va a continuar con el codigo cuando nosotros lo dejemos
. Que es lo minimo que necesita saber la nueva persona para continuar con el trabajo?
. Como se puede implementar una nueva funcionalidad?
. Como se puede llevar nuevo codigo a produccion
. Como se realizan las pruebas
. Quienes son los involucrados en el proyecto
. entre otros

Como documentar?
. Quien es la persona que va a leer esta documentacion?
. Usar un idioma tecnico o coloquial segun la persona que lo vaya a usar

Donde documentar?
. Dentro del propio codigo
. En algun repositorio

Cuando documentar?
. Escribir la documentacion al mismo tiempo que se va desarrollando el codigo

este curso detalla el tema
Curso de Introducción al Technical Writing y Documentación de Código
Cómo documentar en JS https://jsdoc.app/
Tutorial de Markdown
https://www.markdowntutorial.com/

Les recomiendo el Curso de Introducción al Technical Writing y Documentación de Código para aprender un poco más sobre la documentación 😄

Documentacion Basado en los aportes de todos
Documentar es una de las mejores prácticas que podemos hacer cuando estamos en un equipo de trabajo. Dejar por escrito cómo hemos hecho algunas funcionalidades, cómo podría ser mejorado el código y por sobretodo debemos dejar comentarios en el código que ayuden a las personas a ubicarse en qué parte de la aplicación están y qué hacen esas líneas de código.

La documentación debe hacerse clara y entendible pensando en quien la va a leer a futuro.

¿Qué documentar?
Lo mínimo que necesita las personas que quieren colaborar o heredar tu proyecto

Como implementar nueva funcionalidad.
Como se realizan las pruebas.
Como se lleva el codigo a produccion. etc.

¿Como documentar?
Recomendado UML como documentación (Graficos).no necesariamente debe ser texto

¿Dónde documentar?
Propio código.
Sistema de documentación.
Wiki (github https://www.youtube.com/watch?v=RhydZnn7Zqc)
Ficheros externos.
README (https://pandao.github.io/editor.md/en.html)

Puedes documentar tu código en VS Code poniendo:
/**
TITULO DE LA FUNCION
@param PARAMETRO1 FUNCION
@param PARAMETRO2 FUNCION
@param PARAMETRO3 FUNCION
**/

¿Cuándo documentar?
Documentar inmediatamente después de codear.
Cuando se resuelve un problema, documentar la solución.++++