El objetivo de esta guía es ayudarte a hacer tu primera documentación. También podrás usarla para empezar a documentar muchos otros proyectos.
- ¿Qué es una documentación?
- ¿Para qué documentar?
- ¿Por dónde empezar?
- ¿Qué incluir en la documentación?
- Referencias
La documentación es cualquier material comunicable que se utiliza para describir, explicar o instruir sobre algunos atributos de un objeto, sistema o procedimiento, tales como sus partes, ensamblaje, instalación, mantenimiento y uso. [1]
El objetivo de una documentación es ayudar al usuario. Una buena documentación es clara y eficiente. Cuando una documentación es eficiente, el usuario puede encontrar el pedazo de información que necesita rápidamente. Cuando es clara, el usuario adquiere esa información y puede aplicarla para mejorar su uso del producto.
Si quieres que otros desarrolladores trabajen en tu código, vas a tener que documentar. Los colaboradores no llegan de la noche a la mañana por arte de magia. La gente debe querer usar tu producto e involucrarse con él. Si la gente no entiende para qué sirve tu proyecto, no lo va a instalar. Y si la gente no sabe cómo instalar ni empezar a usar tu código, nadie lo va a usar. [2]
Por último, pero no menos importante, tú seguramente volverás a este código dentro de algun tiempo.
Cuando tengas que hacer cambios y mejoras lo más probable es que no entiendas una buena parte del código que escribiste. Quizás podrías tener dudas de cómo empezar a usar la funcionalidad.
Ya estoy convencidx de que debo documentar mi proyecto, pero no tengo idea de por dónde empezar.
El archivo README es la carta de presentación de nuestro proyecto. En este archivo iniciamos al usuario en el propósito, la instalación y el uso de nuestro código.
El lenguaje más popular para elaborar el README es Markdown. Markdown ofrece muchas ventajas al momento de estructurar y organizar textos. Además, es muy fácil de usar. La sintaxis básica de Markdown la puedes encontrar aquí.
GitHub es una plataforma de hospedaje de código para el control de versiones y la colaboración. GitHub permite que tú y otras personas trabajen juntos en proyectos desde donde sea. [3]
Para seguir esta guía, necesitarás una cuenta de GitHub y acceso a internet. No necesitas saber cómo codificar ni utilizar la línea de comandos.
Un repositorio se utiliza a menudo para organizar un solo proyecto. Los repositorios pueden contener carpetas y archivos, imágenes, videos, hojas de cálculo y conjuntos de datos; todo lo que necesita tu proyecto.
Para empezar con tu repositorio ingresa a GitHub y sigue estos pasos:
Por último, enfrentarse a una página vacía sin saber con qué llenarla es difícil. Por esto, aquí incluyo algunas ideas de qué escribir para empezar.
- Empieza explicando qué es lo que hace tu proyecto.
- Pon a tus lectores en el contexto de tu proyecto. Recuerda que pueden leerte tanto usuarios inexperimentados como desarrolladores.
- Incluye un ejemplo de código. Explica cómo funciona y para qué se usa.
- Da instrucciones detalladas de cómo instalar y empezar a usar tu trabajo.
- Añade un enlace para sugerencias. Tus potenciales colaboradores podrían estar interesados en sugerir una funcionalidad. Haz que sea fácil para ellos contactarte.
- Asegúrate de incluir apoyos visuales. Leer lenguaje técnico puede volverse tedioso.
¡Mucho éxito en tu primera documentación!
[1] The Linux Information Project. (2006, Feb. 23). Documentation Definition [Online]. Disponible: http://www.linfo.org/documentation.html
[2] Write The Docs. (2022). A beginner’s guide to writing documentation [Online]. Disponible: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
[3] GitHub. (2022). Hola Mundo [Online]. Disponible: https://docs.github.com/es/get-started/quickstart/hello-world