Escribir Prosa
Estas reglas aplican a la documentación en Markdown y a los comentarios de documentación en código, en cualquier idioma. Las reglas marcadas como "solo Markdown" no aplican a los comentarios de documentación. En esas áreas, los comentarios de documentación siguen las convenciones de su idioma, como los enlaces de documentación [Nombre] de Go. Los skills para tipos de documento particulares, como ADR y glosarios, agregan sus propias reglas además de estas.
Tono
Relajado pero preciso. Escribe como un ingeniero experimentado que explica el tema a otro ingeniero. Evita un lenguaje de especificación excesivamente formal. Prefiere explicaciones claras y naturales que sigan siendo técnicamente precisas. El tono debe ser accesible y conversacional, pero no casual.
Supón que los lectores tienen un conocimiento intermedio del desarrollo de software, pero pueden no conocer los proyectos Dogmatiq o el dominio del documento. Evita la jerga y explica cualquier término técnico que el documento necesite. Imagina al lector como un desarrollador de aplicaciones con unos cinco años de experiencia profesional, que sabe Go pero tiene poca experiencia en algoritmos o matemáticas.
Nombres de archivo (solo Markdown)
Usa nombres de archivo en minúsculas, como glossary.md, a menos que una convención externa requiera lo contrario, como LICENSE o README.md.
Ajuste de línea (solo Markdown)
Reajusta cada párrafo para que cada línea contenga tantas palabras como sea posible dentro de 80 caracteres.
Puntuación
- Usa comillas y apóstrofos rectos (
",') en la prosa, nunca los curvos. Los caracteres no ASCII están bien en bloques de código y fórmulas. - Escribe guiones largos con un espacio a cada lado, como en
palabra — palabra. - Usa un guión largo, no guiones cortos, como separador parentético.
- Usa un guión largo para una aposición que define un término, en listas y párrafos. No uses dos puntos, punto y coma ni paréntesis para esto.
- Considera reformular oraciones o párrafos que contengan muchos guiones largos.
- Usa el punto y coma con moderación, para contraste (A; B no hace), calificación (A; sin embargo B) o consecuencia lógica (A; por lo tanto B). Prefiere un punto si las cláusulas se leen naturalmente como dos oraciones separadas.
- Reemplaza un guión doble (
--) en la prosa con un guión largo cuando corresponda. De lo contrario, sugiere la puntuación correcta.
Ortografía
Usa inglés estadounidense. En caso de duda, sigue go.dev, la documentación de la biblioteca estándar de Go, o la documentación de AWS y GCP.
| EE. UU. (correcto) | No EE. UU. (incorrecto) |
|---|---|
| analyze | analyse |
| behavior | behaviour |
| canceled | cancelled |
| center | centre |
| color | colour |
| initialize | initialise |
| labeled | labelled |
| serialize | serialise |
Enlaces de referencia (solo Markdown)
- Usa enlaces de estilo referencia, nunca enlaces en línea.
- Coloca las definiciones de los enlaces al final del archivo, en grupos que comiencen con un comentario HTML de etiquetado, como
<!-- references -->o<!-- anchors -->. - Ordena cada grupo alfabéticamente por etiqueta. La excepción son los enlaces de versión en un
CHANGELOG.md, que permanecen en orden ascendente de versión, por lo que[0.9.0]va antes que[0.10.0]. - Cuando un término enlazado aparece en forma plural, agrega una definición separada para el plural, como
[instructions]: #instruction, para que la fuente se lea de forma natural. - Cada definición debe usarse al menos una vez. Elimina las definiciones no utilizadas.
- Cada referencia debe tener una definición coincidente. No dejes referencias rotas.
Revisión
Verifica el texto contra cada regla anterior. Para cada problema, cita el texto, nombra la regla que infringe y sugiere una corrección.