doc-refine — Guía para optimizar la experiencia de lectura de documentos técnicos
Límites entre revisión y reescritura
Primero, distinga entre revisión y reescritura: cuando solo se solicite una revisión, proporcione problemas y sugerencias; cuando se haya solicitado explícitamente una modificación, modifique únicamente los documentos autorizados. Ante cambios en el comportamiento o los hechos en lugar de ajustes en la expresión, mantenga la intención original e indique las partes que requieren confirmación.
Proteja antes de simplificar: comportamiento técnico, contratos de API/datos,前提 y condiciones límite, advertencias de seguridad y legales, descripciones alternativas de accesibilidad, ejemplos válidos, enlaces de origen y anclajes estables. El hecho de que el código ya tenga el mismo comportamiento no es suficiente para eliminar la documentación; las repeticiones locales necesarias pueden ayudar a la lectura independiente.
Dos objetivos de verificación
Todas las decisiones se reducen a dos preguntas:
| Axioma | Pregunta para uno mismo | En una frase |
|---|---|---|
| ① Encontrar rápido | ¿Puede el lector objetivo determinar dónde está la información a partir del índice y los títulos? | Señales claras |
| ② Cada párrafo tiene un propósito | ¿Se pierde información necesaria para completar la tarea, comprender el comportamiento o controlar el riesgo si se elimina? | Información completa y concisa |
Realice estas dos comprobaciones para cada contenido. Si no se cumple ① → modifique el título/agregue un diagrama/ajuste la estructura. Si no se cumple ② → verifique los elementos protegidos y las tareas del lector, luego sugiera fusionar o simplificar; no elimine contenido necesario solo por su extensión.
Flujo de trabajo
1. Diagnóstico (lea el texto completo primero, no se apresure a modificar)
Lea el documento objetivo y registre los problemas por sección:
- ¿Puede el título transmitir el contenido de forma independiente sin numeración? (No → violación del axioma ①)
- ¿Aparece la misma lógica/regla en 2 o más lugares? (Sí → violación del axioma ②)
- ¿Ayuda esta explicación de comportamiento al usuario a comprender contratos, limitaciones o resultados? Primero juzgue su propósito, no elimine mecánicamente según "qué es/por qué".
- ¿Son las frases introductorias solo repeticiones de relleno? Se puede simplificar el lenguaje, pero conserve entre ellas la ubicación de los pasos, las advertencias o las limitaciones.
- ¿Hay 3 o más elementos de comparación dispersos en párrafos? (Sí → debería usar una tabla)
- ¿Es un diagrama más fácil que el texto para entender el flujo o el estado? Elija Mermaid según la capacidad del renderizador objetivo o conserve el texto.
- ¿Resuelven los ejemplos dudas reales, recuperación de errores o casos límite? Conserve los ejemplos efectivos para el lector objetivo.
2. Reparación (aplique según la clasificación de axiomas)
Las reglas específicas se encuentran en las secciones §Axioma ① y §Axioma ② a continuación.
3. Verificación (referencia cuantitativa)
Después de la reparación, lea la Lista de verificación según sea necesario para verificar la integridad de la información y el efecto de lectura. No es necesario que todos los números cumplan los estándares: son herramientas de diagnóstico, no leyes; la claridad tiene prioridad y se pueden hacer excepciones.
Axioma ①: Encontrar rápido
Legibilidad de los títulos
Los títulos son señales. Cuando el mantenedor escanea el TOC, debe saber de un vistazo qué contiene cada sección.
Criterio de juicio: Si necesita hacer clic en la sección para saber de qué trata, el título es demasiado amplio.
| ❌ Demasiado amplio | ✅ Legible | Por qué se cambió |
|---|---|---|
5.1 Nivel de tabla | 5.1 CRUD de proyectos (endpoints a nivel de tabla) | "Nivel de tabla" podría ser cualquier cosa |
5.3 Nivel de fila | 5.3 Endpoints de colaboración a nivel de fila | El lector sabe que aquí hay operaciones como asignación/entrega |
5.4 Exportar | 5.4 Exportación CSV completa | ¿Qué formato? ¿Completo o parcial? |
Endpoints | Endpoints HTTP | Eliminar ambigüedad |
Truco: cuando los conceptos centrales son demasiado cortos, agregue calificadores entre paréntesis para complementar información clave. Pero no se exceda: el objetivo es transmitir "¿qué hay en esta sección?" en ≤15 palabras, no escribir un título de tesis.
Arquitectura de la información
- Una sección, un propósito: Organice el contenido según la tarea principal del lector: tutorial, procedimiento, referencia o explicación. Se pueden conservar firmas de API o antecedentes breves; para material extenso, use enlaces cruzados.
- Lo central al principio, los detalles después: Coloque la información más importante al comienzo de la sección o en la parte superior del documento (Divulgación progresiva). La información avanzada/de borde se puede plegar o colocar en un apéndice.
- Principio de autosuficiencia: Un mantenedor que comience a leer desde cualquier página no debería necesitar "conocimientos previos" (Every Page is Page One). Cuando se necesiten conceptos previos, declárelos al principio de la sección y agregue enlaces.
Texto alternativo para diagramas
Use diagramas solo cuando las relaciones, el orden o la comparación sean más claros con ellos; conserve el texto legible y las descripciones alternativas necesarias.
Árbol de decisión:
¿Tipo de información?
├─ Flujo de varios pasos / decisiones con ramas → Diagrama de flujo (flowchart)
├─ Cambios de estado impulsados por eventos → Diagrama de estados (stateDiagram-v2)
├─ Comparación de 3+ elementos × 2+ dimensiones → Tabla
├─ Relaciones de componentes / niveles de arquitectura→ Diagrama + capas
├─ Definiciones / contexto / valores precisos → Texto (por defecto)
└─ Incierto → Texto por defecto (el diagrama es un plus, no decoración)
Mejores prácticas para Mermaid:
- Nodos ≤30: si se supera, el algoritmo de diseño se vuelve ilegible; divida en "visión general → detalles" en múltiples diagramas
- Etiquete las condiciones de las ramas y las relaciones con significado poco claro; las flechas de orden claras pueden no etiquetarse para evitar ruido
- Use
subgraphpara agrupar nodos relacionados TD(de arriba a abajo) es adecuado para jerarquías;LR(de izquierda a derecha) es adecuado para secuencias/tuberías
Diseño de tablas (Principios de Tufte):
- Elimine líneas, sombreados y decoración innecesarios: "Por encima de todo, muestre los datos"
- Diferencia mínima efectiva: las distinciones visuales deben ser lo más sutiles posible pero claras
- Alinee los números por columna para facilitar la comparación visual
- El texto siempre debe ser horizontal, prohibido el texto vertical
Axioma ②: Cada párrafo tiene un propósito
Eliminación de duplicados
Que la misma información aparezca en varios lugares es el enemigo número uno de la mantenibilidad: se modifica uno y se olvida el otro.
Criterios de detección (si se cumple alguno → necesita eliminación de duplicados):
- La misma lógica/regla aparece en 2+ secciones → conserve la fuente autorizada (generalmente la sección del modelo de datos o la máquina de estados), el resto cámbielo por referencias cruzadas
- Después de verificar el comportamiento, los requisitos previos, los riesgos y la lectura independiente, si no hay pérdida de información → fusione o simplifique el párrafo
- El documento repite detalles de implementación → juzgue si el lector los necesita; conserve las explicaciones de comportamiento y los contratos, no elimine con el argumento de que ya están en el código
- Múltiples enfoques equivalentes → dé una recomendación predeterminada; conserve las alternativas necesarias que difieran en compatibilidad, permisos o condiciones de uso
ARID ≠ DRY: La documentación acepta repeticiones necesarias: repetir conceptos de la sección de referencia en un tutorial es razonable. Pero elimine el mantenimiento paralelo: un mismo hecho no puede mantenerse de forma independiente en dos lugares, de lo contrario, uno estará desactualizado.
Simplificación
Elimine todo lo que no sirva a las necesidades actuales del lector.
| Señal de alerta | Cómo solucionarlo | Por qué |
|---|---|---|
| Relleno repetitivo: "En esta sección discutiremos…" | Fusione en una declaración directa | Conserve el posicionamiento de pasos necesario |
| Palabras de relleno: "Cabe señalar que" / "Vale la pena mencionar que" | Simplifique la frase introductoria | Las advertencias o limitaciones en sí mismas aún deben conservarse |
| Abuso de voz pasiva ("es utilizado para…", "será…") | Cambie a voz activa SVO | Más corto, más claro, el lector sabe "quién está haciendo qué" |
| Sinónimos cambiantes (misma función con diferentes palabras) | Estandarice la terminología, una palabra por concepto | Hace explícito el nombre de la función para el lector |
| Oraciones largas y anidadas de difícil lectura | Divida según la lógica | No rompa la relación entre condiciones, excepciones y conclusiones |
| Enumeración de soluciones equivalentes | Opción recomendada al principio, alternativas necesarias después | Conserve las opciones viables bajo diferentes restricciones |
Moderación en los ejemplos
Los ejemplos son la herramienta de respuesta rápida más potente y también el tipo de contenido que más fácilmente se abusa. Write the Docs escribió específicamente "Incluya (algunos) ejemplos" — "algunos" entre paréntesis es una limitación deliberada.
Cuándo usar ejemplos:
- El lector necesita una respuesta rápida y saltará directamente al ejemplo (la primera reacción de muchos)
- Un concepto sin un ejemplo concreto es difícil de entender
- Se demuestra un caso de uso frecuente y real
Cuándo no usar ejemplos:
- Para demostrar algo obvio (Microsoft: "No ilustre puntos obvios")
- Escenarios artificiales que no ayudan a la comprensión; los ejemplos sintéticos claramente marcados y que verifican el comportamiento se pueden conservar
- Agregados solo por "integridad", sin una necesidad real del usuario
- Ya hay suficientes ejemplos; agregar más reduce la capacidad de escaneo
Buenos ejemplos:
- Cubren solo los casos de uso más comunes, no son exhaustivos
- Autónomos y ejecutables (copiar y pegar funciona)
- Progresan de simple a complejo
- Muestran el resultado esperado para que el lector pueda verificar
- Solo omiten el código repetitivo si el ejemplo sigue siendo ejecutable o se han declarado los requisitos previos; conserve las importaciones necesarias, el manejo de errores y el resultado esperado
Malos ejemplos:
- Demuestran lo obvio
- Escenarios artificiales poco realistas
- Un ejemplo intenta cubrir demasiadas variables
- Incluyen manejo de excepciones no relacionado con el ejemplo
- Código que se dice ejecutable pero no se ha verificado; cuando no sea ejecutable, marque explícitamente las limitaciones de verificación
Reglas de ubicación:
- Ejemplo simple de una línea → en línea en el texto principal
- Ejemplo más largo → separado de la documentación de referencia densa (párrafo independiente o sección plegable)
- Ejemplos en documentación de referencia → sea moderado, solo para ilustrar el uso, no mezcle con enseñanza
Referencia rápida de métricas cuantitativas
Las siguientes son solo sugerencias de detección inicial ajustadas según el idioma y el lector; consulte la Lista de verificación para más detalles.
| Dimensión | Punto de partida sugerido | Límites de uso |
|---|---|---|
| Longitud de oración en inglés | Preste atención al anidamiento alrededor de 20 palabras | No aplique mecánicamente al chino, no rompa condiciones y contratos |
| Párrafo | Una idea principal por párrafo | Excepciones y advertencias pueden seguir al párrafo original |
| Lista/pasos | Considere agrupar cuando sea larga | No elimine pasos completos solo para que el número coincida |
| Voz pasiva | Reescriba cuando el sujeto no esté claro | No establezca una proporción obligatoria |
| Mermaid | Considere una visión general y detalle cuando haya muchos nodos | Juzgue según la legibilidad real del renderizado |
| Tabla | Considere dividir o transponer tablas anchas | Conserve las columnas y unidades necesarias para la comparación |
Los números son sugerencias, no estándares de la industria ni leyes de investigación; no cambie hechos, contratos, textos de seguridad o legales solo para cumplir con los números.
Referencia rápida de antipatrones
| Antipatrón | Síntomas | Solución |
|---|---|---|
| Almighty Thud | Documento monolítico, toda la información con el mismo peso, decisiones clave ahogadas | Divida o agregue capas de prioridad |
| Mezcla de tipos | Tutorial con referencias de API, referencia con "por qué" | Separe según Diátaxis |
| Relleno repetitivo | Frases introductorias sin información sustancial | Simplifique el lenguaje, conserve información de riesgo y pasos |
| Sinónimos cambiantes | Misma función llamada con diferentes palabras | Estandarice la terminología |
| Relaciones poco claras | Significado de ramas o flechas requiere suposición | Etiquete relaciones poco claras |
| Chartjunk | Tablas con líneas decorativas y sombreados innecesarios | Elimine decoraciones que no transmitan información |
| Sobrecarga de ejemplos | Ejemplos exhaustivos de todos los escenarios | Conserve solo los casos de uso más comunes |
| Mantenimiento paralelo | Mismo hecho mantenido de forma independiente en varios lugares | Conserve uno, el resto cámbielo por enlaces |