Tema: technical-writing
-
Documentación de incorporación: el camino desde una máquina nueva hasta un cambio fusionado
La documentación de incorporación es un único camino numerado que lleva a quien se incorpora, humano o agente, desde no tener nada instalado hasta un cambio fusionado usando solo lo que está escrito; cada persona nueva corrige aquello con lo que tropezó, y el camino lleva asociado un responsable y una fecha de vigencia.
-
¿Se ganan las páginas de preguntas frecuentes su lugar, y qué evita que se queden obsoletas?
Pregunta abierta: la guía de estilo de GOV.UK prohíbe las preguntas frecuentes en GOV.UK, alegando que el contenido escrito a partir de las necesidades del usuario no las necesita, mientras que el Nielsen Norman Group sostiene que las preguntas frecuentes aportan valor y que la búsqueda por sí sola rara vez basta; ¿qué resultados medibles, reglas de responsabilidad y comprobaciones de obsolescencia han registrado los equipos para las páginas de preguntas frecuentes en la documentación técnica?
-
Diagramas como código con Mermaid: qué hace bien y dónde se detiene
Mermaid genera diagramas a partir de texto dentro de Markdown, de modo que los diagramas conviven con el código, muestran diferencias (diff) en la revisión y se renderizan en GitHub y otros visores; sus límites son un diseño automático que no admite ajuste fino, el tamaño, las diferencias entre versiones del renderizador y la accesibilidad, que requiere palabras clave explícitas de título y descripción.
-
Escribir texto fuente que se traduzca bien
El texto fuente de interfaces y documentación se traduce con limpieza cuando las frases son unidades completas, las cadenas nunca se ensamblan a partir de fragmentos, los plurales y los marcadores de posición pasan por el framework, y se dejan fuera los modismos, el humor y las referencias culturales; las restricciones vienen de cómo funcionan las herramientas al estilo gettext y quienes traducen.
-
Cómo redactar un documento de diseño o RFC sobre el que los revisores puedan decidir
Un documento de diseño debe lograr una decisión antes de escribir código: primero el problema, después objetivos y no objetivos, una explicación a nivel de guía y otra a nivel de referencia, alternativas con los motivos de su rechazo, inconvenientes y una lista explícita de preguntas sin resolver; la estructura sigue lo que piden PEP 1, la plantilla de RFC de Rust y la práctica de documentos de diseño de Google.
-
Actualizaciones de estado durante un incidente: plantilla y frecuencia
Durante un incidente, una sola persona se encarga de la comunicación y publica actualizaciones con una periodicidad fija a partir de una plantilla: estado, impacto visible para los usuarios, lo que se sabe, lo que se está haciendo y la hora de la siguiente actualización. La actualización se publica a la hora prevista aunque no haya novedades.
-
Normas de comunicación asíncrona para equipos distribuidos
Las normas escritas indican qué canal usar para cada tipo de mensaje, en cuánto tiempo se espera respuesta, qué se considera urgente y dónde se registran los resultados; el mensaje en sí empieza por lo que se pide, incluye su contexto y es lo bastante completo para que alguien en otra zona horaria pueda actuar sin preguntar de nuevo.
-
Mensajes de error que indican a usuarios y agentes qué hacer a continuación
Un buen mensaje de error nombra qué falló con el valor real, enuncia la restricción incumplida e indica qué hacer después. Para los agentes añade un código estable, el campo que falla, si un reintento puede servir y, si hay una corrección sugerida, una etiqueta con su grado de confianza.
-
Nombrar documentos y archivos para que se ordenen, se encuentren y perduren
Una convención de nomenclatura de archivos fija los componentes del nombre y su orden, un único separador, el conjunto de caracteres portable, una fecha de estilo ISO que se ordena como texto, números de secuencia con ceros a la izquierda y versiones explícitas; se documenta una vez por carpeta y nunca depende de mayúsculas ni de espacios.
-
¿Cuándo eliminan los equipos de documentación una página en lugar de actualizarla y qué ocurrió después con sus lectores y enlaces?
Pregunta abierta: las páginas obsoletas suelen reescribirse y rara vez se eliminan; MDN describe el estado 410 Gone como señal de que un recurso ya no está disponible y de que la condición probablemente es permanente, pero la mayoría de las páginas eliminadas acaban como redirecciones o 404. ¿Qué criterios de eliminación han usado los equipos y qué pasó después con el tráfico, los resultados de búsqueda y los enlaces entrantes?
-
Guía de estilo para referencias de API: una misma estructura para cada entrada
Una guía de estilo para referencias fija el orden de las secciones (resumen, sintaxis, parámetros, valor de retorno, errores, observaciones, ejemplo), la redacción de la primera frase y cómo se expresan los valores por defecto, las restricciones y las deprecaciones, de modo que lectores y generadores sepan dónde está cada dato.
-
Mantener un glosario del proyecto como vocabulario compartido
Un glosario asigna a cada término del dominio un nombre preferido, una definición, sus cuasisinónimos con las diferencias y un estado. Los documentos expanden las abreviaturas en el primer uso y enlazan a la entrada; al renombrar un concepto, el glosario se actualiza en el mismo cambio que el código y la documentación.
Legible por máquina: JSON