¿Cuáles son algunos consejos para visualizar la documentación técnica?

Para ser honesto, el mayor dolor de cabeza en la documentación técnica es cómo hacer que los conceptos abstractos comprensible. La semana pasada me encontré con una situación típica - para explicar la arquitectura de microservicios a los nuevos internos, confiando en las descripciones de texto para hablar durante medio día, mirando a sus ojos confundidos, de repente me di cuenta de que: documentos técnicos para ser visual, pero visual no es lo mismo que simplemente dibujar unas cajas con unas pocas líneas tan simples.

Elegir el tipo de gráfico adecuado es importante

Cada tipo de documento requiere una visualización diferente. Los documentos de arquitectura utilizan diagramas de arquitectura, las descripciones de procesos diagramas de flujo y las relaciones de datos diagramas ER, lo cual parece de sentido común, pero mucha gente se confunde. He visto a gente utilizar mapas mentales para mostrar la arquitectura del sistema, y acaban desordenando las claras relaciones jerárquicas. Por ejemplo, si quieres ilustrar el proceso de inicio de sesión de un usuario, un diagrama temporal sería más apropiado que un diagrama de arquitectura, porque mostraría claramente el orden de interacción entre los componentes.

Mantener la coherencia visual es fundamental

Esto es muy importante. He visto bastantes documentos técnicos con gráficos de distintos colores, diferentes tamaños de letra e incluso el estilo de las flechas no es uniforme. Esta confusión visual afectará gravemente a la experiencia de lectura. Se recomienda definir un conjunto de especificaciones de diseño antes de empezar: cuál es el color principal, qué colores secundarios elegir, cómo establecer el tamaño de la fuente, cómo unificar el grosor y el estilo de las líneas de conexión. Al igual que Smart Excalidraw, le ayuda automáticamente a mantener la coherencia visual, ahorrándole mucho esfuerzo de ajuste.

La jerarquía debe ser claramente visible

El mayor temor de la documentación técnica es complicar problemas sencillos. Una buena visualización debe permitir al lector ver de un vistazo dónde está el centro de atención y cuál es la jerarquía. Por ejemplo, en un diagrama de arquitectura, los componentes principales deben tener colores más llamativos o tamaños más grandes, y los secundarios pueden debilitarse convenientemente. Mediante una disposición y agrupación razonables, la jerarquía de la información se presenta de forma natural. Recuerdo que una vez optimicé un diagrama de arquitectura de un sistema, simplemente ajustando la posición y el tamaño de los componentes, de modo que la relación jerárquica de toda la arquitectura resulta más del doble de clara.

Las notas y etiquetas deben ser las correctas

La clave no es tener tantas descripciones de texto en el gráfico como sea posible, sino tener el etiquetado necesario en los lugares necesarios. He visto algunos gráficos, cada componente está escrito lleno de instrucciones, el resultado es más bien la gente no puede encontrar el foco. De hecho, sólo tiene que estar en los nodos clave, fácil de producir ambigüedad en el lugar con una descripción concisa es suficiente. Una herramienta como Smart Excalidraw es bueno, genera diagramas con notas bien colocados que no se ven abarrotados.

Al final, lo más importante de la visualización de documentos técnicos no es lo bonito que esté dibujado el diagrama, sino la eficacia con que se transmita la información. A veces, un simple esbozo, siempre que pueda transmitir con precisión el significado, es más valioso que esos enfoques extravagantes pero poco claros sobre la complejidad del diagrama. Al fin y al cabo, el objetivo de nuestra documentación técnica es que se entienda, no presumir.