Siete pasos para documentar sin morir en el intento

Documentar o no documentar, he allí el dilema.

En entornos altamente especializados como el del software, la elaboración de documentación técnica suele ser un quebradero de cabeza o un “mal necesario” para aquellos que subordinan las letras al mundo de los números y la lógica algorítmica.

No obstante, aunque está claro que, como se proclama en los valores del manifiesto ágil, la entrega de productos y servicios funcionales debe anteponerse a la de documentación exhaustiva (obviamente, un manual sirve de muy poco si antes no existe el equipo, aplicación o servicio al que describe); tampoco es menos cierto que la capacidad de dejar un registro documental de cada paso de un proyecto o desarrollo, no sólo sirve de apoyo a la memoria desde tiempos ancestrales -verbigracia las cuevas de Altamira-, sino que también facilita bastante la mejora continua y puesta en práctica de cualquier solución.

Partiendo de tales premisas, se podría admitir entonces que ya que la documentación, aunque no totalmente imprescindible sí es altamente deseable, en pro del bien común es factible lograr que el proceso de creación y escritura de documentos sea lo más sencillo y óptimo posible, incluso para aquellos que no aspiren a ganar un premio literario con este tipo de “obras”. Afortunadamente: “Everything is hard before it is easy”.

 

Algunos pasos esenciales de la escritura técnica

 

  1. A diferencia de los autores de best sellers, cuando se trata de la documentación técnica, no existe el problema previo de buscar una historia inspiradora y con tanto gancho como para mantener viva una saga. Basta con identificar correctamente el objetivo del documento y conocer en detalle el elemento a describir, apoyándose en expertos y en la propia experiencia como usuario para cubrir las expectativas del público potencial. Esto ayudará a centrarse en lo fundamental y adoptar una perspectiva útil para el lector.

 

  1. Una vez definidos los objetivos, se puede pasar a la elaboración de un esquema de contenidos. Con una lista de los ítems a cubrir o bien utilizando una plantilla de estructura -si la hubiese-, siempre resulta más sencillo empezar a desarrollar un borrador. Y es que organizar y priorizar los elementos permite tener una perspectiva más global, pasar a la acción más rápidamente y reducir el stress que pudiera generar inicialmente la tarea.

 

  1. Sintetizar al máximo y escribir con claridad. ¿Es realmente importante? ¿Se puede explicar en menos líneas? Cuando se toma parte de un proyecto por largo tiempo, es fácil caer en la tentación de abundar en detalles o en contextos “históricos”. Sin embargo, intentando ponerse siempre en los zapatos del lector final, es posible identificar los hechos o elementos esenciales y conseguir un texto más cercano a la sinopsis de la película o a la respuesta a las cinco preguntas básicas que a la mayoría de las personas les gusta encontrar cuando buscan información de cualquier tipo: qué, cómo, cuándo, dónde y por qué.

 

  1. El valor de la simplicidad. Así como en literatura y en casi cualquier contenido narrativo se valoran los estilos sencillos y amenos, esta característica cobra aún más valor cuando se trata de temas técnicos. Puesto que se pretende facilitar la lectura de un contenido “de trabajo”, líneas de código y fórmulas aparte, los elementos de “prosa” deben obedecer a una estructura lo más plana posible: con oraciones cortas y del tipo sujeto-verbo-predicado, con verbos activos y palabras entendibles para la mayoría de las personas o, si es inevitable su uso, con acrónimos o términos brevemente definidos y contextualizados. A veces, en aras de la claridad, incluir un glosario puede ser más que necesario.

 

  1. Imágenes, imágenes. En un mundo donde abundan las actualizaciones de Instagram y proliferan los memes hasta en los correos corporativos, está claro que si un diagrama o un gráfico pueden ahorrar tres párrafos de explicación, siempre se debe apostar por la imagen. Pero, en el sentido contrario, si el aporte informativo de un esquema es escaso, confuso o dudoso, se debe evitar el uso gratuito de cualquier ilustración. El tiempo de lectura es valioso.

 

  1. Revisa, que algo queda. Una vez terminado el borrador, es necesario asegurarse de dedicar un espacio a la corrección y validación del documento (desde la estructura, hasta el contenido, la gramática y la forma, bien por los responsables del proyecto o los technical writers, en los casos en los que se cuente con ellos). Posteriormente, habrá que asegurarse de prever el recorrido o vida útil del mismo, para de esa forma programar las actualizaciones que garanticen la validez y pertinencia de los datos y contenidos.

 

  1. El contexto también importa y lo normal es que todos quieran saber más. Así que, siempre que sea posible, es recomendable añadir al final todas aquellas referencias, fuentes y recursos útiles que pudieran necesitar quienes quieran profundizar en los aspectos tratados en el documento y que por razones sinópticas no se incluyeran. Hecho ésto, y trátese del formato o soporte que sea, sólo quedará: ¡publicar!

 

Referencias y recursos útiles:

Tech Writing Handbook. Kyle Wiens, Julia Bluff

Handbook of Technical Writing. Gerald J. Alred, Charles T. Brusaw, Walter E. Oliu

What we talk about when we talk about quality content: 8 common myths

Gráficos e infografías

https://www.lucidchart.com/

https://www.draw.io/

https://www.easel.ly/

 

Imágenes

https://pixabay.com/es/

https://www.pexels.com/

https://unsplash.com/

http://es.freeimages.com/

Iconos

http://www.flaticon.com/

After many years working as a technical journalist in several magazines, newspapers and publishing projects as well as a consultant and specialized trainer for software companies, now I am part of Datio Academy Team. From Academy, we are responsible for the edition, coordination and maintenance of documentation resources, corporative communication, gamification and social media strategies which is a very enriching experience that potentiates our startup culture.

Natalie Campo

After many years working as a technical journalist in several magazines, newspapers and publishing projects as well as a consultant and specialized trainer for software companies, now I am part of Datio Academy Team. From Academy, we are responsible for the edition, coordination and maintenance of documentation resources, corporative communication, gamification and social media strategies which is a very enriching experience that potentiates our startup culture.

More Posts

Follow Me:
LinkedIn

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *