Los estándares de documentación sin los que no puedes vivir

Los estándares que sigas variarán en función del tipo de documentación que vayas a crear. Aquí te daremos algunos de los tipos de documentación más habituales, así como recomendaciones sobre las plantillas que puedes utilizar para establecer tus propios estándares.

Todo proyecto se desarrollará con mayor fluidez si todas las personas implicadas trabajan en sintonía. Todos los miembros del equipo que trabajen en un proyecto necesitan una única fuente de información fiable que puedan consultar en cualquier momento. Sin un plan de proyecto documentado, los miembros del equipo pueden perder de vista la imagen de conjunto y acabar perdiendo tiempo.

Para agilizar y estandarizar la documentación de los proyectos, puedes usar esta plantilla de Confluence, que te garantizará un registro constante de la información esencial relativa a todos los proyectos.

¿Los miembros de tu equipo pierden tiempo porque tienen que explicarles constantemente a los demás cómo hacer las cosas? ¿O acaso alguna vez te has visto pasando mil penurias para completar una tarea o un proceso claves cuando quien sabía cómo llevarlos a cabo no estaba en la oficina?

Estas situaciones son una señal de la importancia de documentar los procedimientos. Básicamente, hay que documentar todo lo que los miembros de tu equipo hagan de forma recurrente, de tal manera que cualquier miembro del equipo pueda realizar la tarea o el proceso en cuestión.

Cuando cuentas con estándares establecidos, la documentación de los procedimientos resulta más eficaz, por no hablar de más fácil de crear. De nuevo, es aquí donde resulta útil tener una plantilla. Por ejemplo, la plantilla de Confluence para artículos de instrucciones te ofrece una fórmula para documentar los procesos.

La documentación para el software y otros productos técnicos puede explicar cómo funciona el producto, cómo usarlo, cómo se creó y cómo se compiló.

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 la documentación para detallar el código, las API y registrar sus procesos de desarrollo de software.

La documentación técnica tiende a ser extensa, pormenorizada y suele actualizarse con frecuencia, por lo que resulta especialmente importante contar con las herramientas adecuadas para garantizar la exactitud y ahorrar tiempo. Por ejemplo, puedes utilizar las plantillas existentes en Confluence o crear las tuyas propias. Confluence también tiene macros que facilitan la actualización o reutilización de texto.

Independientemente del tipo de documentación que estés elaborando, existen unas cuantas competencias esenciales que garantizarán que tu trabajo cumpla tus estándares de documentación y resulte útil para los usuarios.

• Organización. Una cosa es conocer la información que quieres documentar, pero presentarla de forma que se pueda seguir con facilidad es otra bien distinta. Aparte de organizar la información en un orden lógico, también es importante utilizar elementos como, por ejemplo, encabezados de sección y listas con viñetas para guiar a los usuarios de la documentación.
• Claridad. Para que la documentación resulte clara y fácil de entender, hay que elegir el nivel de detalle adecuado. Poner una cantidad insuficiente de información resulta confuso, pero también lo es poner demasiada. Existen otras formas de aumentar la claridad de la documentación como, por ejemplo, ser meticulosos con la gramática, evitar la jerga y elegir palabras concretas en vez de ambiguas (como "a menudo").
• Homogeneidad. Prestar atención a la homogeneidad es una de las cosas más útiles que puedes hacer para cualquiera que vaya a utilizar tu documentación. Por ejemplo, a un usuario le resultará más fácil seguir la documentación de los procedimientos si está escrita de la misma manera que otros documentos de ese tipo de tu organización.

Establecer estándares no solo te ayuda a crear una documentación más adecuada, sino también a distribuirla de forma más eficaz.

Para que resulte útil, la documentación debe ser accesible para todo el equipo. No te interesa que los miembros del equipo guarden información importante en sus discos duros individuales. Tampoco te interesa que tengan que depender de una sola copia impresa que está oculta en un archivador cualquiera. Situaciones como estas provocan confusión e ineficiencia.

Por ejemplo, los miembros del equipo que utilicen versiones distintas de la documentación podrían tener problemas de comunicación o darse recíprocamente más trabajo; o podría darse el caso de que una persona que teletrabajara tuviera que acceder a una documentación que solo existe en formato físico en la oficina.

Puedes ahorrarte estos problemas estandarizando el almacenamiento y la distribución de la documentación. Lo mejor es tener un repositorio centralizado: un único lugar conocido por todos en el que buscar la información más actualizada. Ahora bien, aparte de guardarlo todo en un solo lugar, también tienes que ponérselo fácil a la gente para que encuentre lo que busca allí.

Para nosotros, en Atlassian, ese repositorio centralizado es Confluence, ya que presenta funciones como, por ejemplo, una potente búsqueda, árboles de páginas estructurados y el archivado de páginas, que garantizan que siempre resulte sencillo buscar y encontrar el contenido, así como que este esté actualizado.

En Confluence, cada equipo o proyecto dispone de un espacio para organizar la documentación que les concierne. Pueden crear una jerarquía de páginas para mantener toda la información organizada y visible desde el árbol de páginas. Los empleados pueden seguir espacios o subpáginas que les interesan para enterarse cuando cambie el contenido. Para distribuir un espacio o una página en particular, puedes usar el botón de compartir o bien añadir un comentario a una página y etiquetar en él a otros miembros del equipo. Los empleados pueden hacer búsquedas en todas las páginas abiertas de Confluence, así como emplear filtros para delimitar la consulta por creador, fecha de publicación o espacio.

Del mismo modo que cada documento necesita actualizaciones constantes, sucede lo propio con el sistema que utilizas para archivar y organizar la documentación. Por lo tanto, no te olvides de establecer tus estándares también aquí. ¿Con qué frecuencia tienes que revisar y ordenar tu archivo de documentos? Reserva esas fechas en el calendario.

Ahora que tienes una visión general de lo que son los estándares de documentación, puedes empezar a desarrollar o revisar directrices para los tipos de documentación que necesita tu equipo. El tiempo que inviertas en establecer estos estándares te ayudará a crear documentación con mayor rapidez y aumentará la utilidad de esa documentación para tu equipo.