writing-guidelines

Writing Guidelines

Audiencia Objetivo: Este documento proporciona estándares de escritura para agentes de IA (LLMs) al crear documentación, comentarios de código y contenido técnico para proyectos de desarrollo de Polkadot.

Principios Fundamentales (Método Zinsser)

Reglas de Escritura Empresarial

• Lidera con el resultado, no con el proceso

• Usa voz activa: "Arreglamos el bug" no "El bug fue arreglado"

• Escribe para el lector que no sabe nada sobre tu trabajo

• Presenta las conclusiones primero, luego explica si es necesario

• Una idea por oración, un tema por párrafo

Escritura Relacionada con Código

• Los nombres de variables son oraciones: hazlos claros, no ingeniosos

• Los mensajes de error deben decir a los usuarios qué hacer después

• La documentación debe responder "por qué", el código muestra "qué"

• Descripciones de PR: Declara cambios e impactos, omite el proceso

• Mensajes de commit: Qué cambió y por qué, en tiempo presente

La brevedad es poder. Reduce cada oración a sus componentes más limpios. Elimina cada palabra que no cumple una función. Reemplaza frases con palabras. Elige palabras simples sobre las complejas.

Eliminación de Desorden

• Corta calificadores: "muy", "bastante", "algo", "más o menos", "prácticamente"

• Elimina pares redundantes: "todos y cada uno", "primero y principal", "varios y diversos"

• Elimina aclaraciones innecesarias: "Es importante notar que", "El hecho de que"

• Evita frases infladas: Usa "ahora" no "en este punto en el tiempo"

• Borra jerga sin sentido: "utilizar" → "usar", "implementar" → "hacer"

• Comienza con lo que hace, no cómo funciona

• Usa ejemplos concretos sobre descripciones abstractas

• Escribe instrucciones como comandos: "Ejecuta tests" no "Deberías ejecutar tests"

• Prueba tu escritura: ¿Puede alguien seguirla sin que estés ahí?

• Asume inteligencia pero no conocimiento

La Prueba Zinsser

Antes de confirmar cualquier texto escrito, pregunta:

1. ¿Puedo cortar esta oración a la mitad?

2. ¿Hay una palabra más simple?

3. ¿Necesita el lector saber esto?

4. ¿Estoy diciendo esto dos veces?