Close

Crear una mejor documentación

Acabas de comenzar un proyecto y tienes que entregar la documentación en seguida (mal asunto).

Puede que al principio te dé un poco de vértigo, pero no te preocupes, que para eso estamos aquí. Abajo tienes documentación sobre cómo crear documentación [(wink)]. Se trata de una guía paso a paso con consejos de expertos que te orientarán a lo largo de todo el proceso.¡Empecemos!


Por qué es tan importante

Básicamente, la documentación permite sacar más trabajo adelante. Ahora bien, al igual que la mayoría de las cosas buenas que suceden de forma inexplicable, la documentación va mucho más allá, ya que ayuda a los usuarios y equipos a:

Gastar menos energía mental

Saca el trabajo adelante sin dejarte la piel y con el menor esfuerzo posible.

Crear coherencia

Asegúrate de que todo el mundo tenga acceso a la misma información, los mismos procesos y los mismos planes.

Reducir la carga de trabajo

Incorpora nuevos miembros al equipo rápidamente para que puedan ponerse manos a la obra en seguida.

Mejorar la marca de la empresa

Deja claro cómo quieres tratar a tus empleados (a nivel interno) y a los clientes (a nivel externo) prestándoles atención y mostrando disposición a ayudarles.

Si no ofreces algo de valor, nadie se fijará en tu propuesta. Tienes que saber cómo presentar la información que intentas ofrecer para que el público al que te diriges la acepte y entienda por qué debería importarle.

Qué es la documentación

La documentación es exactamente lo que estás pensando: un conjunto de documentos. Una brújula que guía a tu usuario final medio. Un manual de estrategias que orienta al ingeniero o la ingeniera de software que llevas dentro.A nivel más técnico, la documentación suele hacer referencia al texto o las ilustraciones que acompañan un software. Sirve como guía para explicar cómo funciona y cómo usarlo. Los equipos de software pueden consultar la documentación cuando estén hablando de los requisitos del producto, las notas de una publicación o las especificaciones de diseño. Los equipos técnicos pueden usar los documentos para detallar el código, las API y registrar sus procesos de desarrollo de software. A nivel externo, la documentación suele presentarse en forma de manuales de usuario para administradores de sistemas, equipos de soporte y otros usuarios finales.

Toda documentación debe cumplir dos objetivos básicos:

1. Informar a los usuarios

2. Ayudar a los usuarios a conseguir un objetivo concreto

Cuando vayas a implementar un proceso de documentación, empieza por definir el tema de interés u objetivo para que las partes interesadas sepan en seguida de qué trata lo que van a leer.

Tipos de documentación

Como hemos comentado antes, la documentación puede presentarse de muchas formas, tanto a nivel interno como externo. Cada tipo de documento requiere un registro, un tono de voz, un formato, un contenido, un público y unos colaboradores distintos. Entre los tipos de documentos más habituales se incluyen los siguientes:



Documentación interna
ilustracion-documentacion-equipo

Documentación para equipos

La documentación de equipo sirve para aportar visibilidad sobre el trabajo en curso. Así, los equipos pueden trabajar como lo que son: equipos. Pueden ser documentos como planes de proyectos, la planificación de los equipos, informes de estado, notas de reuniones y cualquier otra cosa que un equipo pueda necesitar para funcionar de forma práctica y eficiente. Este tipo de documentación suele ser detallado para que todo el mundo pueda trabajar en la misma dirección.

ilustracion-documentacion-referencia

Documentación de referencia

La documentación de referencia informa a la empresa sobre temas, procesos y políticas importantes. Pueden ser políticas que haya creado el departamento de RR. HH., unos procesos legales implantados para la contratación de proveedores externos o artículos de instrucciones sobre cómo conseguir los beneficios que ofrece la empresa. Recuerda que la documentación de referencia la redacta un grupo reducido de personas para un público amplio y diverso, por lo que es importante que el contenido sea fácil de digerir.

ilustracion-documentacion-proyecto

Documentación del proyecto

La documentación de proyectos está relacionada, evidentemente, con proyectos concretos y aporta una estructura necesaria al desarrollo de un producto. Incluye propuestas, documentos sobre los requisitos de un producto, directrices de diseño o esbozos, hojas de ruta y otros datos necesarios para el desarrollo, y estas aportaciones proceden de los gestores de proyectos, ingenieros, diseñadores y otras partes interesadas.



DOCUMENTACIÓN EXTERNA
ilustracion-documentacion-sistemas

Documentación de sistemas

La documentación de sistemas incluye el código, las API y otros procesos que indican tanto a desarrolladores como a programadores qué tipos de métodos y funciones pueden usarse para desarrollar cierto software, así como las limitaciones y requisitos correspondientes.Los fragmentos de código, como las llamadas y respuestas a API, son fundamentales en este tipo de documentación.

ilustracion-documentacion-usuarios-finales

Documentación para usuarios finales

La documentación de usuario suele ser la más visible de todas. Su lectura y comprensión debe ser sencilla, y debe actualizarse cada vez que se publique una nueva versión del software en cuestión. Suele presentarse en forma de archivos "README", guías de instalación y del administrador, bases de conocimientos de productos y tutoriales (estos últimos son los más útiles de todos). Y, al igual que en el caso de la documentación de referencia, estos documentos los redacta un grupo reducido de personas para un grupo amplio de consumidores, por lo que es fundamental que el contenido sea fácil de digerir.

Si incluyes ejemplos en la documentación, tu público lo agradecerá. Sirven como puente para ayudar a comprender conceptos e ideas, y transmiten al lector que realmente sabes de lo que hablas.

Crear una documentación

Al final, tu objetivo es hacer que la documentación sea útil a los lectores. A continuación, para ayudarte un poco con tu documentación, te dejamos más documentación en formato tutorial ("metadocumentación" podríamos llamarlo).

1. Investiga

¿Qué es lo que tienen que saber los usuarios sobre tu producto, proyecto o API? Utiliza la herramienta de análisis para descubrir qué búsquedas se hacen, entrar en los foros y grupos de debate de la comunidad online y realizar investigación de usuario y pruebas de usabilidad. Asegúrate también de conocer bien tu producto y de saber explicar fácilmente las preguntas de los usuarios, las funciones nuevas y los flujos de trabajo.

2. Empieza

Indica claramente qué temas trata la documentación y por qué el lector debería consultarla.

3. Anota los detalles

Haz un esquema y escribe un borrador del contenido. Utiliza una voz y un tono que sean adecuados para tu público (pero dándole un toque humano) y utiliza un lenguaje coherente y conciso en todo momento. Explica las ideas importantes de forma clara.

4. Aplica formato

Organiza las páginas de modo que sean fáciles de seguir de principio a final. Quita todo lo que sea relleno y estructura el contenido intercalándolo con ilustraciones, como diagramas, capturas de pantalla e imágenes.

5. Revisa

Pide a alguien que revise las palabras homófonas, como "tu" demostrativo y "tú" pronombre. Explica a los revisores el objetivo de la documentación en cuestión. Así podrán centrarse en las ambigüedades o pasos que echen en falta.

6. Publica

Tras revisar y modificar la documentación, ya podrás publicarla. Una vez que lo hayas hecho, presta atención a los comentarios que te lleguen de los lectores. No tiene por qué quedarse así para siempre.

Reglas de oro

Como has visto, la documentación no consiste en reunir una serie de palabras e instrucciones sin más. Así es: hay un método para todo. Ten presentes estas pautas básicas antes, durante y después de crear la documentación (y también mientras duermas):

Lo bueno, si breve, dos veces bueno

La documentación debe incluir la información justa y necesaria para que no haga falta abrir un ticket de ayuda. Indica los puntos clave de cada tema y da a los lectores la opción de ampliar la información si así lo desean.

Las ilustraciones son clave

Las ilustraciones facilitan muchísimo la comprensión. Cosas como el diseño de un producto, código de muestra, demos de productos, capturas de pantalla y tutoriales en vídeo ayudan mucho al lector a entender bien los conceptos, instrucciones y tareas. No te olvides del diseño, la legibilidad y la distribución del contenido para que sea fácil de digerir.

Conoce a tu público

Ponte en la piel del usuario. Conócelo bien. Sigue el recorrido que hace por tu producto y por la documentación. Esto debería servirte de guía siempre a la hora de decidir qué escribir y cómo hacerlo.

Ponte manos a la obra

La mejor documentación es clara, concisa, informativa y, sobre todo, útil para el público al que va dirigida. Prueba software de colaboración en equipo como Confluence para la documentación; verás como dedicas menos tiempo a buscar cosas y más a poner cosas en marcha.

Más información