Saltar a contenido

Escribiendo Documentación

Una buena documentación es lo que hace que valga la pena utilizar esta wiki. Esta página aborda tres aspectos: qué hace que la documentación sea buena, qué debe (y qué no debe) incluirse en la wiki y cómo dar formato a las páginas para que mantengan la coherencia con el resto del sitio.

¿Qué Define una "Buena" Documentación?

Una buena documentación es más que un simple "repositorio de información útil". Una guía eficaz para redactar buena documentación consiste en poder responder a las siguientes preguntas:

  • ¿Qué es esto?
  • ¿Qué hace esto?
  • ¿Por qué o para qué se utiliza esto?
  • ¿Cómo se utiliza esto?

La usabilidad y la accesibilidad deben ser siempre una prioridad; por ello, ten en cuenta los siguientes puntos al redactar documentación:

  • Escribe para alguien que sabe menos que tú. Asume que el lector es capaz, pero que carece de tu contexto. Describe las siglas la primera vez que las utilices.
  • Una página, un tema. Si te encuentras escribiendo frases como "como nota al margen" o "aunque no está relacionado...", es probable que ese contenido deba ir en su propia página.
  • Muestra, no solo cuentes. Un ejemplo breve, un comando o una captura de pantalla suelen explicar más en menos espacio que un párrafo de texto.
  • Mantén la información actualizada. Una página con información errónea es peor que no tener una página; si un proceso cambia, actualiza la documentación en la misma pull request.
  • Escribe en lenguaje claro. Prefiere frases cortas y palabras cotidianas frente a la jerga técnica; cuando el uso de tecnicismos sea inevitable, defínelos una vez.
  • Se conciso desde el principio. Coloca la información más importante al inicio y deja los antecedentes o los casos excepcionales para más adelante. La mayoría de los lectores escanean el texto en lugar de leerlo de principio a fin.

Este es un documento vivo

Si te encuentras enseñando a alguien una práctica de documentación que no aparece aquí, ¡añádela! Consulta nuestra guía de contribución para obtener información técnica.

La documentación debe tener en cuenta las dificultades que un nuevo usuario encontrará durante su aprendizaje y ser capaz de resolverlas a lo largo de la lectura. En esencia, una documentación "excelente" es aquella que lleva al lector desde un nivel de principiante absoluto hasta uno de competencia razonable, proporcionando suficientes recursos adicionales para profundizar en el tema, incluyendo:

  • Breves explicaciones sobre la tecnología, sus procesos y los estándares asociados a ella.
  • Una explicación de por qué, cómo y/o para qué se utiliza esta tecnología, incluyendo un breve vistazo a su configuración.
  • Enlaces útiles a referencias externas, incluyendo conocimientos fundamentales y cualquier otro recurso que facilite la comprensión.

No es necesario ser un experto en una materia para poder escribir sobre ella con competencia. Considera utilizar tu propia experiencia de aprendizaje como referencia al presentar la información.

Pautas de Contenido

La documentación debe ser accesible. Sin una estructura clara o un orden lógico de las ideas, es imposible que la documentación resulte tan útil para los demás como lo sería para ti. También es importante tener en cuenta que no toda la información debe ir en la wiki, ni todo tiene por qué estar en el mismo lugar. Algunas reglas generales:

  • Aquí va el conocimiento general; los datos confidenciales específicos de clientes, no. Los procesos, estándares y guías prácticas pertenecen a la wiki. Las credenciales, los contratos con clientes y cualquier información confidencial deben almacenarse en su ubicación correspondiente con acceso restringido; incluye un enlace si es necesario, pero NUNCA agregues esa información aquí.
  • Cada página necesita un lugar. Antes de crear una página nueva, comprueba si encaja en alguna sección existente. Si no encaja en ningún sitio, es señal de que quizás necesitemos una sección nueva, no una página suelta.
  • Los nombres de archivos y carpetas deben ir en minúsculas y separados por guiones. Usa network-assessment-checklist.md, no Network Assessment Checklist.md.
  • Ambos idiomas, siempre que sea posible. Cada página debe existir tanto en inglés como en español. Si solo puedes escribir una versión de inmediato, añade la otra posteriormente.
  • No dupliques información; enlázala. Si la información ya existe en otra página, incluye un enlace a ella en lugar de copiarla. El contenido duplicado tiende a desincronizarse.
  • Otra persona debería leerlo antes de que se integre. Una segunda opinión permite detectar pasos poco claros que, para quien los redactó, tienen todo el sentido del mundo. Solicita siempre una revisión externa.

Especificaciones de Formato

Se trata de normas técnicas que ayudan a garantizar que todas las páginas de la wiki tengan el mismo aspecto y comportamiento.

Utiliza este documento como referencia

Este mismo documento sirve de buena referencia para tus propios textos. Puedes consultarlo directamente en formato sin procesar para ver el código fuente de la página.

Metadatos

Todas las páginas deben comenzar con un bloque de front matter (cabecera de metadatos), delimitado al inicio y al final por tres guiones (---) y siguiendo el formato de pares llave:valor:

Warning

Las llaves deben estar en minúscula, en inglés y deben respetar el indentado.

---
title: Título de la página
description: Resumen de una frase que aparece en los resultados de búsqueda
ts y vistas previas.
authors:
  - Autor 1
  - ...¿y tal vez Autor 2?
date:
  created: Cuándo se escribió este documento por primera vez, en formato AAAA-MM-DD. 
  updated: Cuándo se actualizó este documento por última vez, en el mismo formato.
lang: Etiqueta de idioma, según si está en inglés (en) o español (es).
---

Encabezados

Markdown (el lenguaje en el que están escritas las páginas de la wiki) utiliza encabezados para organizar el contenido a lo largo de la página. Usa un único # (H1) para el título de la página y, a continuación, ## (H2) y ### (H3) para establecer la jerarquía. No saltes niveles; un ### no debería aparecer directamente debajo de un #.

Formato de Texto

Estilo Sintaxis Resultado Pauta
Negrita **texto** texto Términos clave, títulos, nombres de botones y primeras menciones de conceptos importantes.
Cursiva *texto* texto Énfasis sutil dentro de una oración para cambiar el tono del lector o resaltar una palabra específica y evitar ambigüedades.
Código en línea `código` código Binarios y programas ejecutables en el equipo del usuario, variables de entorno.
Ángulos en código `<texto>` <texto> Valores que deben sustituirse en un comando, como una dirección IP o una credencial de usuario.

Bloques de Código

Utiliza bloques de código para mostrar código, comandos y entradas/salidas específicas de la terminal. Especifica siempre el lenguaje para obtener un resaltado de sintaxis preciso:

```bash
git status
```

Avisos (Admonitions)

Utiliza avisos para destacar información sin interrumpir el flujo de la página:

!!! tip "Título opcional"
    El contenido va aquí, con una sangría de cuatro espacios.

Tipos comunes: note, tip, warning, danger, example.

Enlaces e Imágenes

Enlaces

Al redactar, a menudo necesitarás enlazar tanto contenido interno como externo.

Para contenido interno, utiliza enlaces relativos para otras páginas de la wiki: [Contributing](contributing.md). Tanto las rutas absolutas como las relativas son válidas, pero ten en cuenta que todas las rutas parten del directorio docs/, en lugar de la raíz "real" del proyecto.

Para referencias externas, puedes incluir enlaces en el texto cuando proceda, pero es recomendable añadir una sección de "Lectura Adicional" cuando la documentación requiera referencias complementarias. Ten en cuenta las siguientes buenas prácticas:

  • Organiza por relevancia. Agrupa los enlaces por tema o propósito (p. ej., "Documentación oficial", "Tutoriales", "Recursos de la comunidad").
  • Utiliza texto descriptivo. Evita enlazar URLs sin contexto; en su lugar, explica qué contiene el recurso. Por ejemplo: [Documentación de Forgejo - Protección de ramas](https://forgejo.example.com) en lugar de solo la URL.
  • Archiva enlaces externos. Utiliza servicios como Wayback Machine o Archive.today para crear copias permanentes de recursos externos importantes. Incluye el enlace de archivo como alternativa en un formato claro, como [texto](enlace) ([archivo](enlace-de-archivo)).
  • Evita el exceso de enlaces. Demasiados enlaces externos pueden abrumar a los lectores; prioriza los recursos más valiosos.

Imágenes

En el directorio de nuestro proyecto, mantenemos un directorio assets/ independiente que replica la estructura de la documentación. Guarda las imágenes relacionadas en un directorio con el mismo nombre que la documentación, ubicado en el nivel correspondiente.

wiki/
└ docs/
  └ assets/
    └ getting-started/
      └ writing/
        └ ¡Aquí van las imágenes para este documento específico!