Cómo afrontar un proyecto de documentación grande I

documentacion grande

Empezar un proyecto de documentación grande siempre es interesante y estimulante, pues inicias un largo camino que vas a transitar durante meses. En ese camino, te encontrarás pegas y problemas, y según como hayas recibido las especificaciones, tendrás que definir más o menos aspectos clave del documento.

Por experiencia, se que un proyecto de documentación grande puede ser abrumador por momentos, pero es cuestión de organizarse un poco y tener algunas estrategias claras. En este artículo, te contaré algunas de las estrategias que actualmente estoy siguiendo, de cuáles me están funcioando y cuáles no.

Mi gran proyecto de documentación

Quizás hayas notado que desde hace unos meses no se actualiza el contenido en esta web, y quizás hayas pensado que he tirado la toalla… pues no, no he tirado la toalla, ni mucho menos (un skater nunca se rinde). Es que estoy inmerso en un megaproyecto de documentación, desde hace unos meses, y ocupa todo mi tiempo y ganas de escritura.

No puedo dar detalles por confidencialidad, pero estoy redactando la documentación oficial de una aplicación software que tiene bastante tirada. O mejor dicho, de un conjunto de aplicaciones de una familia de software.

documentación grande

Por supuesto, tengo que aprender a la perfección el manejo de todas estas aplicaciones, que no son pocas. Como serán documentos públicos colgados en internet, tengo que hacer redacción SEO, y cumplir unos mínimos de calidad que normalmente no tendría en cuenta con la documentación interna. Al final, son un conjunto de cosas que suben la dificultad y complejidad del trabajo.

Pero lo realmente abrumador es el volumen. En mi caso, estoy hablando de un documento que puede contener entre 500 y 1000 páginas. Coger esa piedra y masticarla de una tacada sería tarea de titanes, por lo que la primera estrategia que he tenido que adoptar ha sido, necesariamente, el Divide y Vencerás.

Divide y vencerás

Esta estrategia, popularizada por Julio César, consiste en dividir un problema en muchos problemas pequeños.

En vez de coger la documentación como un todo, ve por partes. Tanto en lo conceptual como en lo práctico, que es la redacción en sí.

ave césar

Divide el documento en varias secciones o partes lógicas, quédate con una, y vuelve a dividirla en pequeñas tareas, así hasta que te encuentres cómodo con el volumen de información. Cuando hayas terminado esa parte, incorpórala al conjunto, como si estuvieras construyendo un puzzle.

Cosas a evitar:

  • No pretendas tener una visión global exacta de todo el documento en los inicios, ni siquiera a corto plazo.
  • No redactes un día sobre el bloque A, al siguiente sobre el bloque C, y luego otra vez en el A.
  • Céntrate en un conjunto de páginas, sácalas adelante y evita que otras tareas de documentación se crucen. Sobretodo, no vayas dejando cosas por terminar o a medias. Y si lo haces, ves apuntando en algún sitio lo que te dejas.

De cara a poder hacer un divide y venderás, necesitarás tener un primer índice de todo el proyecto.

Crea un índice de la documentación

La creación de un índice inicial es necesaria, pero tampoco te obsesiones con esta tarea, pues lo más seguro es que el índice sufra varias modificaciones durante todo el proceso de redacción. Si en tu proyecto ya se te ha proporcionado un índice que debes cumplir a rajatabla, perfecto, pero en caso contrario sigue leyendo.

índice grande

Según el volumen de tu documentación, puedes empezar haciendo índices de nivel 1, nivel 2, nivel 3, etc. Lo importante es que no te pierdas en índices imaginarios que todavía están muy lejos, que no entres en detalles en aquellas partes de la documentación que todavía no has empezado a redactar o no están claras del todo.

En cuanto tengas tus primeros índices, aplica el divide y vencerás. Es decir, coge una porción del mismo, y céntrate en la misma. Aplica divide y vencerás tantas veces como sea necesario, y cuando por fin tengas un conjunto pequeño de páginas que redactar, ponte manos a la obra.

Define las especificaciones del documento, y usa plantillas

Algo a tener en cuenta con los proyectos de documentación grandes es la coherencia.

Es importante que todas las páginas sigan el mismo esquema en lo que se refiere a encabezados, secciones, uso de negritas, enlaces, imágenes, maquetación, etc.

Y sí, además, has de cumplir con las normas SEO, necesitarás sí o sí tener predefinidas estas cosas, y aplicarlas conforme redactes, no después.

especificaciones

Merece la pena gastar algo de tiempo dejando esto por escrito, en un documento aparte, con todas las convenciones o especificaciones que va a cumplir tu documento. Y utilizar plantillas, para que las páginas nuevas vengan ya con muchas de esas especificaciones cumplidas.

Si ya te proporcionaron las especificaciones para el documento, tan solo tienes que cumplirlas. En caso contrario, tendrás que hacerlas tú: si no sabes por donde empezar, no te preocupes, empieza a redactar y cuando tengas varias páginas ya verás más claro qué estrategias seguir.

Mi consejo es que hagas todas las pruebas que tengas que hacer sobre un conjunto realmente pequeño de páginas, para evitar tener que modificar muchas entradas, más tarde.

Aunque como escritores, a veces tendremos que olvidarnos de las normas, y aprovechar el momento de escribir…

Carpe Diem

Aprovecha el momento, o mejor dicho, la inspiración.

No olvides que, como escritor, eres una persona creativa. A tu manera, eres un artista. Y, como los artistas, hemos de tener en cuenta el papel de la emoción en nuestra capacidad de escritura. Esto quiere decir que, cuando te sientas con ganas de escribir, debes escribir, sin importar donde y cuando estés.

Evidentemente, tiene que gustarte escribir, si ves la escritura como algo pesado y aburrido, mal vas para esto. Al final, son tus ganas y tu capacidad de aguantar los momentos bajos lo que decidirá si eres capaz de funcionar en esto, a largo plazo.

En cuanto a lo de escribir siempre que tengas ganas, no siempre es posible. De hecho, mi experiencia al respecto está siendo un poco negativa. Escribir desde el espacio de oficina es, definitivamente, el peor sitio desde el que escribir. Y redactar entre llamadas de teléfono y casos de soporte informático… definitivamente NO. Eso puede funcionar si estás con documentación pequeña, pero con un volumen grande, necesitas estar al 100%.

Las normas están para saltárselas

Define normas y convenciones para el documento, pero tampoco te obsesiones con ellas. Si en un momento dado queda mejor hacer algo de otra forma que la que dicta la norma, hazlo.

normas documentación

Ser un talibán de la escritura no va a hacer que tus textos sean mejores, más ligeros, fáciles de entender o de seguir.

Más vale hecho, que perfecto

De esto ya hablamos en un artículo de introducción al technical writing.

Lo importante es que entregues un contenido que sea útil. Si no entregas nada, no hay manera de recibir feedback, o de saber si lo que haces le sirve a alguien. Así que no te obsesiones con el producto perfecto, eso está muy lejos de tus capacidades ahora mismo, tan solo entrega contenido útil.

No te vengas abajo si al principio el resultado no luce como te gustaría, ya lo irás mejorando poco a poco. Recuerda que esto es documentación para internet, no un producto que va a ir a librerías. Más tarde podrás mejorar esas secciones que han quedado regular, conforme te vengan las ideas o recibas feedback de tu audiencia.

Conclusiones

En este artículo hemos hablado de algunos aspectos clave para redactar proyectos de documentación grande, o al menos de algunos de ellos. Si quieres aportar algo a este tema, puedes usar el formulario de más abajo, para dejar tus comentarios (y sí, puedes poner enlace a tu web, si dices algo con sentido).

En próximas entradas intentaré ampliar el tema, o enfocarlo desde otras perspectivas. Ánimo con tus proyectos de documentación, y recuerda que en NSS estamos disponibles para todo tipo de proyectos de escritura, tan sólo contacta y lo hablamos.

[Total:2    Promedio:5/5]