A煤n no tienes acceso a esta clase

Crea una cuenta y contin煤a viendo este curso

Documentaci贸n

23/26
Recursos

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.

Aportes 27

Preguntas 2

Ordenar por:

驴Quieres ver m谩s aportes, preguntas y respuestas de la comunidad? Crea una cuenta o inicia sesi贸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.

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

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.

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鈥檚 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 鈥淲iki鈥, 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.
La documentaci贸n podr铆a estar dentro del README del repositorio

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.

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

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.++++