Este mes marca un año desde que asumí mi rol actual y más técnico de mi carrera. No tenía la intención de mantenerlo en secreto. Realmente, simplemente no influyó mucho en mi escritura.
En este punto, estoy dando a entender que claramente lo ha hecho. El puesto me ha expuesto a una variedad de sistemas informáticos creados por varias personas a lo largo del tiempo. Todos estos sistemas me han obligado a asimilar rápidamente un volumen inmenso de conocimientos técnicos.
Teniendo en cuenta mis afinidades por la ingeniería y la escritura de software, una cosa que me ha llamado la atención en mi función es la documentación. Probablemente debería haber previsto esto, pero no lo logré mientras me mantenía frenéticamente al día con todo, ¿de acuerdo? He visto documentación impresionante que guía al lector en un viaje a través del código y la documentación que casi hizo que mis ojos se vidriaran de las paredes de texto apenas relevante.
Después de leer decenas de páginas, desarrollé una intuición de lo que separaba lo ejemplar de lo lamentable. Lo que sigue es una destilación consciente de esa intuición.
La forma platónica (at) del bien
¿Qué hace una buena documentación? Fundamentalmente se trata de organización y facilidad de seguimiento visual. Aquí hay algunas manifestaciones de eso, sin ningún orden en particular.
Los ejemplos, recordatorios, advertencias, etc., se incluyen en recuadros destacados. Esta práctica no solo dirige la atención del lector a su contenido, sino que ayuda a romper lo que de otro modo sería una pared uniforme de texto.
Una pizca de colorido formato especial también es excelente para hacer que la página se duplique como una referencia rápida. Por ejemplo, si el lector está familiarizado con la página pero necesita buscar esa advertencia importante, es más fácil para ellos desplazarse hasta encontrar el cuadro que buscarlo con Ctrl-F, lo que podría fallar si no lo hacen. recordar la redacción del contenido.
Los fragmentos de código, ya sea en línea o en una sección formateada separada, tienen estilo monoespaciado. Si el código está en su página de documentación, probablemente esté destinado a usarse o verificarse en un proyecto. Ambas son razones suficientes para que su código salga de la textura.
Puntos de bonificación cuando el código en línea tiene un fondo ligeramente sombreado. Nuevamente, esto es para ayudar a identificarlo durante un escaneo visual. Los fragmentos grandes de código deben encerrarse en algo así como un cuadro de llamada. Si hay mucho código que vale la pena leer, haz que sea imposible pasarlo por alto.
Los enlaces se incluyen generosamente. Los autores de la documentación deben vincular a páginas en tantos sistemas relacionados como sea posible. ¿Alguna vez has visto documentación con demasiados enlaces? No lo creo.
Los datos relacionales se organizan en tablas. Lo mejor de las tablas es que muestran asociaciones. Estos se extienden tanto horizontalmente, en el que un elemento posee múltiples atributos, como verticalmente, en el que muchos elementos comparten la misma clase de atributo. Las computadoras se basan en la asociación. Eso es todo una variable asignada, la base de prácticamente todos los lenguajes de programación, en realidad es un valor asociado con un nombre o ubicación de referencia.
ANUNCIO
Las tablas también son otra gran señal visual. No puedo hablar de las preferencias de todos, pero mi cerebro absorbe mejor la información si se presenta en una tabla en lugar de un párrafo. Imagine que tiene que recordar todo lo que pueda sobre una página que leyó solo una vez hace dos semanas, con solo un vistazo rápido. ¿Qué te recordaría mejor: mirar una página con una tabla grande o una con solo texto?
El autor y los equipos involucrados proporcionan información de contacto. El software cambia, pero los documentos no siempre se mantienen al día. Cuando eso sucede, es útil saber con quién consultar las actualizaciones. Cualquier cosa ayuda, incluso un nombre, pero la información de contacto más útil es un correo electrónico del servidor de listas del equipo. Los compañeros de equipo individuales van y vienen, pero el servidor de listas suele hacer ping al equipo sin importar quién esté en él.
Se incluyen diagramas. Todo lo que se aplica a las tablas se aplica a los diagramas, pero más. Las relaciones se ilustran con formas simples, que nuestros cerebros depredadores son buenos para procesar. Los diagramas son fundamentales para comprender los microservicios porque hay mucha lógica más allá de una aplicación o servicio en particular bajo consideración.
Malos hábitos que debes dejar como, bueno, malos hábitos
Más allá de la ausencia de las anteriores, aquí hay algunas características que, por su presencia, hacen que la experiencia de consumo de documentación sea frustrante.
La organización es pobre. La mala organización adopta muchas formas, pero la más notoria es la ausencia o inconsistencia de los títulos de las secciones. Incluso si no hay una tabla de contenido vinculada internamente, tener encabezados para desplazarse hace que sea mucho más fácil distinguir lo que busca de los detalles irrelevantes que lo atascarán.
No hay indicación de la veracidad de la información. Esta es astuta porque es comprensiblemente tentador asumir que si está en el documento, es verdad. Pero, ¿realmente tiene la evidencia fáctica para afirmar eso? El software supera la capacidad de los desarrolladores para escribirlo. A veces los autores simplemente se equivocan.
Hay un par de formas de identificar documentos no confiables. Una es la presencia de palabras como «trabajo en progreso», «provisional», «propuesto», etc., especialmente cuando la página no se ha actualizado por un tiempo. ¿Se finalizaron esos detalles equívocos, los desarrolladores se olvidaron de actualizar la página o se desechó el proyecto?
Otro signo de dudosa precisión es un documento que hace grandes afirmaciones sin enlaces y que ninguna otra página corrobora. Si ves esto, piénsalo dos veces antes de confiar en lo que lees.
El formato no coincide. Además del hecho de que se ve mal y puede hacer que la página sea ilegible, el formato descuidado muestra que el autor copió y pegó sin ningún esfuerzo por contextualizar o adaptar la información. A veces, la información es igual de precisa, pero otras veces el contexto faltante puede llevar al lector confiado por el camino equivocado.
Esto no es para arrojar dudas sobre los autores que intentan exprimir la producción de documentación cuando su tiempo ya es escaso. Acabo de ver que esto resultó lo suficientemente malo como para advertir que buscar un formato irregular es solo cuidarse a uno mismo.
ANUNCIO
Incluyendo un script e instruyendo a los lectores para que simplemente lo ejecuten. Nunca jamás, simplemente ejecute un script. Las intenciones del autor suelen ser buenas. Quieren dejar que el lector se descargue de alguna carga cognitiva. Pero el autor nunca puede estar seguro de que el caso de uso del lector se alinea con lo que pretendía con el guión o tiene las habilidades para evaluar si esto es así.
Por otro lado, el autor puede haberse basado en suposiciones poco realistas o simplemente haber escrito un guión chapucero. No tienes que ignorar el guión; solo tienes que leerlo antes de usarlo para cualquier cosa.
Escriba los documentos que desea leer en el mundo
Lamentablemente, no puede hacer que otras personas escriban documentos de la manera que usted desea. Puedes intentarlo, pero te verás como un idiota. El mejor enfoque es para tú escribir documentación que se adhiera a las mejores prácticas. No solo es más útil cuando consulta sus notas, sino que inspirará a otros a mejorar su juego.
Si bien he estado siguiendo algunos de los hábitos constructivos antes mencionados desde el principio, muchos de ellos los tomé porque los vi en otro lugar y pensé: «Voy a comenzar a hacer eso». Esa persona también podrías ser tú.
