Errores comunes en los documentos creados por ingenieros y cómo solucionarlos

Durante los últimos seis meses, nuestro equipo de desarrollo ha adoptado el enfoque de "docs-as-code" (puede obtener más información sobre nuestro viaje en este ). Al revisar regularmente la documentación creada por mis colegas de la División de Tecnología, compilé una lista de los problemas más comunes que se encuentran al escribir documentación técnica.

En el artículo, le mostraré cómo solucionar estos problemas utilizando las herramientas del enfoque "docs-as-code".

Asunto 1. “La redacción de documentos no está bajo nuestra responsabilidad”

Tratar con la documentación de manera ad-hoc es como pegarse un tiro en el pie para todo el equipo de desarrollo. Si el equipo carece de la capacidad, es una razón de peso para hacer que el mantenimiento de la documentación sea más predecible y basado en la tecnología.

Arreglar:

• Integre el enfoque de "docs-as-code" para el desarrollo de la documentación. De esta forma, puede actualizar la documentación de forma iterativa, junto con el código base, sin el riesgo de acumular deuda técnica.
• Desarrolle o integre un espacio o una plataforma que pueda generar documentos técnicos y servir como una única fuente de información.
• Utilice un entorno de desarrollo integrado (IDE). Un IDE le permite incorporar complementos y crear scripts personalizados para el desarrollo de documentación. es una excelente herramienta para escribir documentos, pero es posible que tenga sus favoritas entre las aplicaciones.
• Instale un complemento de revisión ortográfica para protegerse contra los errores tipográficos. Agregar el complemento a su IDE es un proceso rápido y fácil.
• Adopte las pautas internas especialmente diseñadas por su empresa, teniendo en cuenta los conocimientos de la comunidad de redacción técnica (si tiene alguna), para establecer un enfoque estandarizado para desarrollar documentación dentro de la empresa. Seguir estas pautas agilizará el proceso de documentación, ahorrando tiempo al contemplar qué y cómo escribir con precisión.
• Automatice las comprobaciones en función de las directrices para reducir o eliminar significativamente el tiempo de revisión de documentos.
• Modele todo lo posible y acuerde con el equipo la estandarización de los componentes de la documentación.

Ofreceré valiosos recursos que aumentarán su confianza mientras trabaja con documentación técnica. Creo que estos recursos son lo suficientemente completos como para equiparlo para manejar documentos técnicos de manera efectiva:

• El " " sirve como un manual completo para la documentación del desarrollador. Cubre todo lo que necesita saber sobre formato, puntuación, enumeración y adición de bloques de código. Esta guía es suficiente y ha sido una referencia valiosa para desarrollar nuestras pautas internas, de las cuales tomamos prestadas algunas mejores prácticas.
• “ " es un libro de lectura obligatoria para cualquier persona involucrada en el trabajo con la documentación del desarrollador, ya sea que la esté desarrollando, escribiendo o manteniendo. El libro presenta a varios autores renombrados y estimados en el campo de la escritura técnica.

• " de Anne Gentle, escritora técnica, es una guía práctica que muestra la cultura de la documentación en OpenStack. A través de ejemplos prácticos, la autora explica por qué la documentación debe gestionarse en GitHub y cómo implementar procesos tecnológicos para una documentación eficaz. El libro también ofrece información valiosa conocimientos sobre cómo escribir documentación profesional, independientemente de si es un desarrollador o un escritor técnico.

• También mencionaré las pautas internas para escribir documentación técnica, que deben incluir plantillas y reglas de formato. Estas directrices existen en todas las empresas. Por lo general, se desarrollan en colaboración con un escritor técnico pionero y campeones de documentos de desarrollo y evolucionan a medida que crece la cultura de documentación dentro del equipo.

Número 2. Escribir documentación en solitario

Desarrollar toda la documentación solo y luego enviarla para su revisión conlleva el riesgo de crear documentación redundante o irrelevante que puede no alinearse con el propósito previsto.

Arreglar:

• Comience siempre con un esquema y compártalo con el líder de su equipo, el propietario del producto, el escritor técnico o cualquier colega dispuesto a brindar su opinión experta.
• Escriba paso a paso y asigne solicitudes de extracción para revisión en los mismos colegas mencionados anteriormente.
• Recopile y trabaje en la retroalimentación.
• Considere los comentarios. Y tómelo con calma con el tono de voz de revisión, a veces puede ser duro, pero es simplemente una peculiaridad del proceso de revisión.
• No pase por alto el flujo de documentación. A continuación se muestra el flujo general adoptado en nuestra empresa, pero las características de este flujo pueden depender tanto de un equipo de desarrollo como de la empresa:

Tema 3. “Los que necesitan entender entenderán”

De vez en cuando escucho de los equipos: “Estoy escribiendo para el equipo de desarrollo”, “los que necesitan entenderán”, “así es como evolucionó históricamente dentro de nuestro equipo”.

Pero la jerga profesional y los anglicismos requieren adecuación y consistencia. El uso excesivo de ellos puede conducir a una documentación que se asemeja a las notas de un ingeniero loco.

Para la documentación, use las palabras y estructuras más simples posibles. Uno de los principios fundamentales es escribir para desplazarse. La documentación puede ser difícil de escribir, ya que a menudo es extensa, pero los lectores rara vez la revisan de cabo a rabo. En cambio, tienden a desplazarse o utilizar la búsqueda de palabras clave. Por lo tanto, el texto debe ser fácilmente comprensible cuando se abre desde cualquier parte.

Arreglar:

• Consulta los términos en inglés y la jerga profesional utilizando diccionarios y normas vigentes (o simplemente búscalos en Google). Si una palabra existe en el diccionario, escríbala de acuerdo con las reglas ortográficas de su idioma.
• Si la palabra no está presente en el idioma, escríbala en el idioma original y proporcione una traducción a su idioma entre paréntesis.
• Agregue la palabra a la sección del glosario y las abreviaturas a la lista de abreviaturas y acrónimos. Esto es especialmente importante para las abreviaturas "propietarias" (no importa cuánto se mencione o se escriba sobre PO, su significado sigue siendo una de las preguntas comunes al leer la documentación).
• Coherencia: respete el estilo de escritura y las abreviaturas elegidos en toda la documentación (mejor para toda la documentación disponible en su empresa).
• Planifique cuidadosamente la navegación por el documento. Debería haber una forma rápida de encontrar la sección relevante sin tener que leer todo el documento. Por lo tanto, es esencial estructurar cuidadosamente el contenido con encabezados claros y concisos. Las plantillas de documentación interna deben desarrollarse por simplicidad y conveniencia.

Problema 4. Escribir documentación simultáneamente en varios lugares

Para la documentación, es crucial tener una única fuente de verdad: un espacio donde pueda encontrar la información necesaria sin preocuparse por su precisión. Para nuestra documentación técnica, una plataforma desarrollada internamente sirve como tal espacio. Evitar la fragmentación de la documentación en diferentes espacios es fundamental para no inducir a error a nadie con información desfasada.

Arreglar:

• Antes de publicar documentación tecnológica en cualquier lugar, asegúrese de que no exista en otro lugar, si surgiera que la empresa utiliza varios espacios para compartir conocimientos.
• Archive o elimine (si tiene la propiedad) la documentación técnica obsoleta. Si le preocupa la eliminación prematura (por ejemplo, debido a enlaces externos a la página), agregue una llamada que indique que la página está desactualizada y la ubicación actual de la documentación de los documentos válidos, donde se deben realizar más actualizaciones.
• Si encuentra información o conocimientos valiosos, agréguelos a la documentación. No lo dejes en Slack ni en ningún otro lado, especialmente en chats privados. ¡Conocimiento que vale la pena compartir!

Publicado por Anna Goncharova