En la ingeniería de software profesional, existe un abismo entre un proyecto que «funciona» y un producto que es «mantenible». Muchos desarrolladores creen que tener un archivo README.md es suficiente, pero si observamos a los referentes de la industria como Flutter o Angular, notaremos que la documentación no es un anexo, sino una extensión de la arquitectura.
Documentar no se trata de explicar qué hace una función (para eso está el código limpio), sino de explicar el contexto, las reglas de juego y la visión del negocio.
Al final de este documento te comparto los templates para que tengas un buen punto de partida
Los 4 Pilares de la Documentación Profesional
Para que un repositorio sea considerado de «clase mundial», debe cumplir con estos cuatro niveles de información:
1. Doc Comments (El «Porqué» interno)
A diferencia de los comentarios comunes, los Doc Comments (como /// en Dart o /** */ en Java/TS) están diseñados para ser consumidos por herramientas de generación de API.
- Propósito: Explicar el razonamiento detrás de una implementación compleja y los efectos secundarios de una función.
- Regla de Oro: Si el código explica el qué, el comentario debe explicar el porqué.
2. Getting Started (Fricción Cero)
El éxito de un proyecto depende de qué tan rápido un nuevo desarrollador puede hacer su primer «Hello World».
- Contenido: Requisitos de entorno, variables de configuración (
.env.example) y comandos de ejecución inmediata. - Objetivo: Reducir el Time-to-First-Commit al mínimo posible.
3. Contributing Agreement (Las Reglas de Juego)
Indispensable para escalar. Define cómo se deben enviar los cambios al repositorio.
- Incluye: Estándares de Git (Conventional Commits), flujo de Branching (GitFlow o Trunk Based), y requisitos de Testing para que un PR sea aprobado.
4. Architecture Decision Records (ADR)
Es la memoria histórica del proyecto.
- Función: Documentar por qué se eligió una tecnología o patrón específico sobre otro. Esto evita discusiones cíclicas en el equipo y justifica la deuda técnica estratégica.
Docusaurus: Elevando la documentación a un producto
Para proyectos de gran escala, un simple archivo de texto no es suficiente. Aquí es donde entran herramientas como Docusaurus, que nos permiten tratar la documentación como si fuera código.
¿Por qué usar Docusaurus en 2026?
- Versionamiento Nativo: Puedes tener documentación específica para la v1.0 y la v2.0 de tu software simultáneamente, algo vital en bibliotecas de Angular o Flutter.
- Basado en Markdown (y MDX): Permite escribir en texto plano pero insertar componentes interactivos de React dentro de la documentación.
- Búsqueda e Indexación: Incluye soporte para Algolia, permitiendo que el equipo encuentre respuestas en milisegundos, reduciendo la necesidad de interrumpir a otros (aplicando la Regla de los 15 minutos).
La documentación como ventaja competitiva
Un código bien documentado reduce drásticamente el costo de mantenimiento y el tiempo de onboarding. Al adoptar estándares de equipos referentes de Google, dejas de ser un programador que entrega tareas y te conviertes en un Ingeniero de Software que construye sistemas sostenibles.
Template Readme
# (Ingrese nombre del proyecto)
// En caso de que el proyecto se le hayan cambiado los nombres pueden agregar en la primera linea lo siguiente:
Este proyecto inicialmente fue conocido con los siguientes nombres:
## Descripción
Una breve introducción del proyecto donde dejemos en claro sus funcionalidades.
## Datos de liderazgo
* Nombre líder linea de conocimiento y su usuario de red.
* Nombre PO y su usuario de red.
## Keywords (palabras claves del proyecto)
Esto con fines de facilidad de busqueda desde las herramientas organizacionales
## Documentos principales
* Enlace al documento de acuedos de contribución [Contributing Agreement](CONTRIBUTING.md).
* Guía de Adecuar ambiente local [Getting Started](GETTINGSTARTED.md).
## Canal de comunicaciones
En el siguiente enlace (enlace al canal) podrá suscribirse a nuestro canal para estar al tanto de las nuevas características adicionadas.
## Repositorios relacionados
Si existen repositorios relacionados se pondrá una breve descripción y un enlace a los mismos
Template del contributing agreement
# Contributing Agreement
Este proyecto sigue la licencia descrita en el LICENSE.md (enlace al documento)
## Acuerdos de software (obligatorio)
Este proyecto esta basado en el siguiente código de conducta(enlace al CODE_OF_CONDUCT.md) y contamos con las siguiente convenciones
de código (enlace a la wiki donde explicamos nuestras convenciones) las pruebas de software deben seguir la siguiente convención
(enlace a la wiki donde explicamos nuestras convenciones). En este proyecto manejamos el siguiente estándar para el manejo de ramas (enlace wiki)
también manejamos el siguiente estándar de commits (enlace). Para realizar un PR exitoso consideramos que debes seguir los siguientes pasos (enlace).
Para escribir documentación de nuevas carácteristicas o cambios en alguna de ellas debemos seguir el siguiente estándar de documentación (enlace estándar).
## Modelo de Garantias (obligatorio)
Como equipo hemos llegado al acuerdo que una nueva contribución a la rama principal tendrá un tiempo de estabilización de X días y en la rama estable de Y días. Durante este tiempo todo equipo contribuyente dará soporte durante ese tiempo acordado, únicamente a la funcionalidad contribuida. Este soporte incluye solución de errores, vulnerabilidades y deuda técnica sobre los mismos. Esto también incluye los comentarios realizados por los maintainers. En caso de que se cumpla el tiempo y aún queden pendientes, se prorroga hasta que no existan comentarios ni pendientes sobre el software. Si para el momento, de realizar el lanzamiento de una versión estable no se ha dado solución, los cambios no saldrán hasta la siguiente versión estable y se reiniciará el periodo de estabilidad de la característica. En caso de encontrar un incidente sobre los cambios en proceso de estabilización se debe documentar por qué el incidente no se pudo detectar en momento de QA. La persona a cargo de QA debe evaluar si es posible una mejoría en el proceso. También se debe revisar los test pues los mismos deben mapear la mayoría de escenarios posibles. No se aceptará aumentos a la deuda técnica de software, por tanto debe ser igual a cero. En caso de que un equipo desee contribuir un cambio sobre una característica que no se ha estabilizado. Se reinicia y se delega al nuevo contribuyente la estabilidad de la misma durante el periodo acordado. No se aceptarán cambios en la rama principal, en caso tal que no se pueda cumplir el tiempo de estabilización por una próxima salida de una versión estable. Por ejemplo, para un equipo que considere que el periodo de estabilización es dos semanas si se propone un PR faltando una semana para la publicación de la rama estable, no se aceptaran hasta que se hay desplegado la versión lts. Se deben incluir datos de contacto del equipo que de soporte a la nueva característica. [Agregar acuerdos adicionales bajo el modelo de garantías).
## Canales de comunicación (obligatorio)
En este proyecto contamos con los siguientes canales de comunicación:
* Canal para informar errores (issues) (enlace al canal de comunicación) el horario de atención es:
* Canal para informar vulnerabilidades de software (enlace al canal) el horario de atención es:
* Canal para resolver dudas o inquietudes referentes al uso del software (enlace al canal) el horario de atención es:
* Canal para sugerir nuevas carácteristicas (features) a la solución (enlace) el horario de atención es:
## Programa de despliegue de versiones estables (opcional pero preferible)
Durante el 2023 y el 2024 tendremos las siguientes fechas tentativas de despliegue de versiones estables:
* Versión 6.x Octubre 23 del 2023
* Versión 7.x Marzo 23 del 2024
* Versión 8.x Septiembre 23 del 2024
Dado lo anterior no se aceptaran cambios sobre la rama principal en las fechas :
* del 8 al 23 de Octubre del 2023
* del 8 al 23 de Marzo del 2024
* del 8 al 23 de Septiembre del 2024
## Definición de hecho (Definition of Done) (opcional preferible)
## Roadmap de la solución (opcional preferible)
Estas son nuestras futuras features:
Para la versión 6.x se planea desplegar las siguientes características :
* Variante Botón
* Fix en ...
* ...
[Esta sección también puede vivir en un enlace externo y se pondrá el enlace a la misma]
## Maintainers (obligatorio)
Este documento fue creado por el equipo de Maintainers de la solución. Los actuales miembros al equipo de manteiners son:
* Nombre Completo A, Usurio de red
* Nombre Completo B, Usurio de red
* Nombre Completo C, Usurio de red
* Nombre Completo D, Usurio de red
* Nombre Completo E, Usurio de red
* Nombre Completo F, Usurio de red
Template Getting Started
# Getting Started
En este documento explicaremos como puedes adecuar tu ambiente local.
## Herramientas que necesitas instalar
Lista de herramientas de software necesarias para poder ejecutar el código en el ambiente local. Debe también comentar que versión de software se utilizará.
## Guía de instalación
Esta sección describe el paso a paso para levantar el ambiente local.
## Autores del Documento
Un listado de los autores y fechas de actualización de documentación por ejemplo:
- Daniel Herrera 17/6/2023 y usuario de red
- Esteban Toledo 3/3/2023 y usuario de red
- Diana Patricia 12/12/2022 y usuario de red
Repositorio con docusaurus ejemplo
https://github.com/weincoder/show_error_handler/tree/main/docs
Espero que esta información te sea util