¡Hola a todos!
Me llamo Masha, soy ingeniera de control de calidad en el grupo de empresas Tinkoff. El trabajo en QA implica muchas comunicaciones con diferentes personas de varios equipos, y además, he sido gerente y conferenciante de programas educativos, por lo que mi mapa de comunicaciones era lo más amplio posible. Y en algún momento, exploté: comprendí que ya no podía más, no podía más con las toneladas infernales de tablas y documentos ilegibles.
Seguramente cada uno de ustedes se ha imaginado ahora lo que estoy diciendo y ha sudado frío: listas de apellidos sin orden alfabético, tablas con cientos de columnas con un formato desordenado, tablas con miles de filas en las que hay que hacer girar el dedo en el mouse para ver los encabezados, toneladas de páginas de instrucciones no numeradas, cientos de correos enviados entre sí con datos que hay que analizar y sistematizar y encajar en las mismas tablas ilegibles.
Y así, cuando me calmé un poco, decidí escribir este artículo. Hablaré sobre cómo llevar una documentación no productiva de manera adecuada (incluso a veces conveniente). Espero que el artículo se difunda por la red y el nivel de caos en los departamentos cercanos al desarrollo, aunque sea un poco, disminuya, y la gente (yo incluida) sea un poco más feliz.
Herramientas
La documentación de productos a menudo se guarda junto con el código, y eso es bueno. Pero la documentación no productiva suele guardarse en cualquier lugar. A menudo, la gente intenta transferir información de diferentes lugares a Confluence, y nosotros no somos una excepción. Así que aquí está la historia sobre ello.
En general, Confluence es un motor wiki avanzado. Permite trabajar con datos en diferentes formas de visualización: texto con formato, tablas, diversos gráficos. Es una herramienta muy interesante y potente, pero si no sabes cómo prepararla, obtendrás un basurero más de documentos ilegibles. ¡Te enseñaré a prepararlo!
Macros
Casi toda la magia de Confluence se basa en macros. Hay muchas macros, y se pueden combinar entre sí. Algunas son de pago y otras gratuitas, más adelante habrá diferentes ejemplos de macros con enlaces a la documentación correspondiente.
La interfaz para trabajar con macros es muy sencilla. Para agregar un macro, debes hacer clic en el más y seleccionar el elemento deseado de la lista.
Si el macro es autosuficiente, es decir, no requiere la inserción de nada más dentro de sí mismo, se verá como un bloque.
Si se necesita colocar algo dentro del macro para que funcione, se verá como un marco.
Dentro de un marco se pueden colocar tantas otras cosas como se desee, siempre que haya lógica en tu pirámide.
Cada macro tiene una vista previa: se puede ver de inmediato si has completado y configurado el macro correctamente.
Plantillas
Además de los macros, hay una herramienta conveniente de autocompletado de contenido: la plantilla.
Se pueden utilizar plantillas al crear cualquier página: simplemente haz clic en los tres puntos junto al botón 'Crear' y selecciona la plantilla deseada.
Entonces, toda la información de la plantilla se añadirá a la página creada.
Cualquiera puede crear páginas a partir de plantillas, pero solo quienes tienen permisos pueden crear o editar las plantillas. En la plantilla se pueden añadir instrucciones adicionales sobre cómo debe llevarse la página.
La magia de las tablas
De hecho, como técnico, amo tiernamente las tablas y puedo empaquetar casi cualquier información en ellas (aunque no siempre sea eficiente). Las tablas son claras, estructuradas, escalables, ¡mágicas!
Pero incluso una entidad tan maravillosa como la tabla puede arruinarse. No obstante, también se puede utilizar adecuadamente e incluso mejorar. De eso hablaremos a continuación.
Filtración (plugin de pago)
Cualquier tabla enorme y poco legible puede hacerse un poco menos enorme y un poco más legible mediante filtración. Para ello se puede usar un macro de pago. .
Dentro de este macro se debe colocar la tabla (incluso la más fea, lo importante es introducirla completamente). En el macro se pueden seleccionar columnas para filtrar desde un menú desplegable, un filtro de texto, numérico y un filtro por fechas.
Imagina que toda la información sobre los candidatos para todos los puestos se registra en una lista tabular. Naturalmente, no estará ordenada, ya que las personas no llegan a las entrevistas en orden alfabético. Y necesitas saber si has entrevistado a un determinado solicitante antes. Simplemente debes introducir ese caos en el macro de filtración, añadir un filtro de texto por apellido, ¡y voilà, la información está en tu pantalla!
Es importante mencionar que filtrar tablas enormes puede afectar el rendimiento del sistema y el tiempo de carga de las páginas, por lo que meter una tabla enorme en un filtro es una solución temporal; lo mejor es establecer un proceso en el que las personas no tengan que crear tablas enormes e ilegibles (un ejemplo de proceso se dará al final del artículo).
Clasificación (plugin de pago)
Con la ayuda de un macro mágico también se puede establecer una clasificación por defecto para cualquier columna y numerar las filas. O puedes hacer clic en cualquier columna de la tabla que está dentro del macro de filtro, y se realizará la clasificación por esa columna.
Por ejemplo, tienes la misma tabla con los postulantes y necesitas estimar cuántas entrevistas se realizaron en un mes determinado; clasifica por fecha y disfrútalo.
Tablas dinámicas (plugin de pago)
Ahora pasemos a un caso más interesante. Imagina que tu tabla es enorme y necesitas hacer algunos cálculos sobre ella. Por supuesto, puedes copiarla a Excel, calcular lo necesario y cargar los datos de nuevo a Confluence. O puedes aplicar una vez el macro y obtener el mismo resultado, pero además actualizado.
Por ejemplo: tienes una tabla que recopila datos de todos los empleados: dónde se encuentran geográficamente y qué puestos ocupan. Para contar cuántas personas hay en cada ciudad, debes elegir en el macro «Tabla dinámica» la fila por la que se agregan los datos (ubicación) y el tipo de operación (suma).
Por supuesto, puedes agrupar por varios criterios a la vez, todas las posibilidades se pueden consultar .
Gráficos (plugin de pago)
Como ya mencioné, no a todos les gustan las tablas tanto como a mí. Desafortunadamente, la mayoría de los gerentes no las quieren en absoluto. Sin embargo, a todos les gustan los gráficos coloridos.
Los creadores de Confluence, sin duda, lo sabían (seguramente también tienen jefes que aman los informes y gráficos, ¿quién no?). Por lo tanto, se puede utilizar el macro mágico . En este macro se debe introducir la tabla dinámica del punto anterior, y voilà: tus datos grises y aburridos están bellamente visualizados.
Por supuesto, este macro también tiene configuraciones. El enlace a la documentación de cualquier macro se puede encontrar en el modo de edición de dicho macro.
La facilidad de agregación
La información de los puntos anteriores probablemente no fue una revelación para usted. Pero ahora sabe exactamente cómo utilizar macros, y yo puedo pasar a la parte más interesante del artículo.
Etiquetas
Es problemático cuando la gente guarda información en un solo artículo no estructurado o en una enorme tabla. Aún peor es cuando partes de esta información no solo están mal redactadas, sino que también están esparcidas por los rincones de Confluence. Afortunadamente, hay una manera de recopilar información dispersa en un solo lugar. Para ello, debes utilizar (conocidas por todos en las redes sociales como hashtags).
Cualquier página puede tener una cantidad ilimitada de etiquetas. Si haces clic en una etiqueta, serás dirigido a una página de agregación, donde encontrarás enlaces a todos los materiales con esa etiqueta, así como a un conjunto de etiquetas relacionadas. Las etiquetas relacionadas son aquellas que a menudo aparecen en la misma página.
Propiedades de las páginas
También puedes agregar otro macro interesante a la página para estructurar la información: . Dentro de él, debes presentar una tabla de dos columnas, siendo la primera la clave y la segunda el valor de la propiedad. Además, el macro se puede ocultar de la página para que no interfiera en la lectura del contenido, pero, aun así, la página estará marcada con las claves necesarias.
Presta atención al ID: es conveniente asignarlo para enlazar diferentes grupos de propiedades a diferentes páginas (o incluso diferentes grupos de propiedades en una misma página).
Informes
Se pueden generar informes basados en etiquetas. Por ejemplo, el macro recopila todas las páginas con un conjunto específico de etiquetas.
Pero el informe más interesante es el macro . Este también reúne todas las páginas con un conjunto específico de etiquetas, pero en lugar de simplemente mostrar una lista, crea una tabla (¿captas la conexión con el principio del artículo?), donde las columnas son las claves de las propiedades de la página.
Se genera una tabla resumen con información de diferentes fuentes. Es agradable notar que tiene funciones útiles: diseño adaptable, clasificación por cualquier columna. Además, esta tabla de informes se puede configurar dentro del macro.
Al configurarlo, se pueden eliminar algunas columnas del informe, establecer un estado predeterminado o la cantidad de registros a mostrar. También se puede asignar un ID a la propiedad de la página para ver solo la información relevante.
Por ejemplo, tienes múltiples páginas de empleados, y esas páginas tienen un conjunto de propiedades sobre la persona: qué nivel tiene, dónde se encuentra, cuándo se unió al equipo, etc. Estas propiedades están marcadas ID = employee_inf. Y hay un segundo conjunto de propiedades en la misma página, que recopila información sobre la persona como parte del equipo: qué rol desempeña, en qué equipo se encuentra, etc. Estas propiedades están marcadas ID = team_inf. Así que al compilar un informe, puedes mostrar solo información de un ID o de dos directamente, según sea más conveniente.
La belleza de este enfoque es que cada uno puede recopilar la tabla de información que necesita, que no duplicará nada y se actualizará con la actualización de la página principal. Por ejemplo: al líder de equipo no le importa cuándo se unieron sus desarrolladores, pero sí le importa qué rol desempeña cada uno en el equipo. El líder de equipo recopilará su informe sobre el equipo. Y al contador no le importa quién cumple qué rol, pero sí le importan los títulos — él recopilará su informe sobre los puestos. Al mismo tiempo, la fuente de información no se duplicará ni se transferirá.
El proceso final
Instrucción
Entonces, podemos estructurar de manera hermosa y agregar información de manera efectiva en Confluence usando macros. Pero en un mundo ideal, se debería hacer para que la nueva información esté inmediatamente estructurada y sea capturada en todos los mecanismos de agregación ya utilizados.
Aquí la combinación de macros y plantillas será de ayuda. Para obligar a las personas a crear nuevas páginas en el formato correcto, se puede usar la macro "Crear desde plantilla". Esta macro añade un botón en la página, que al ser presionado crea una nueva página desde la plantilla que necesites. Así, obligas a las personas a trabajar de inmediato en el formato que necesitas.
En la plantilla desde la cual permites crear la página, es necesario añadir previamente etiquetas, la macro "Propiedades de la página" y la tabla de propiedades que necesites. También recomiendo agregar instrucciones sobre qué valores deben rellenar la página y los valores de las propiedades.
Entonces, el proceso final se verá así:
- Creas una plantilla para información de un tipo específico.
- En esta plantilla, añades etiquetas y propiedades de la página en la macro.
- En cualquier lugar conveniente, crea una página raíz con un botón, al hacer clic en el cual se crea una página hija a partir de una plantilla.
- Permite que los usuarios potenciales que generarán la información necesaria (según la plantilla requerida, haciendo clic en el botón) accedan a la página raíz.
- Recopilas un informe sobre las propiedades de la página a través de las etiquetas que especificaste en la plantilla.
- Te alegras: tienes toda la información necesaria en un formato conveniente.
Puntos ocultos
Como ingeniero de calidad, puedo afirmar con confianza que nada en el mundo es perfecto. Incluso las tablas divinas no son perfectas. Y en el proceso mencionado anteriormente hay puntos ocultos.
- Si decides cambiar los nombres o la composición de las propiedades de la página, tendrás que actualizar todos los objetos creados para que sus datos se reflejen correctamente en el informe consolidado. Es triste, pero, por otro lado, obliga a pensar detenidamente en la 'arquitectura' de tu conjunto de información, lo cual es una tarea bastante interesante.
- Tendrás que escribir una cantidad considerable de instrucciones sobre cómo llenar las tablas de información y usar las etiquetas. Pero, por otro lado, puedes simplemente compartir este artículo con todas las personas necesarias.
Ejemplo de almacenamiento de documentación no comercial
A través del proceso descrito anteriormente, se puede organizar el almacenamiento de casi cualquier información. La belleza del enfoque radica en que es universal: cuando los usuarios se acostumbran a él, dejan de generar desorden. También hay un gran (pero no gratuito) beneficio: la posibilidad de recopilar estadísticas diversas al vuelo y crear gráficos atractivos de ellas.
Pondré un ejemplo de nuestro proceso de gestión de información sobre el equipo.
Para cada persona en el equipo, decidimos crear una tarjeta de empleado. En consecuencia, tenemos una plantilla en la que cada nuevo individuo crea su tarjeta y lleva toda su información personal.
Como puedes ver, tenemos una tabla de propiedades detallada y ya hay instrucciones sobre cómo llevar esta página. Parte de las etiquetas son proporcionadas por los empleados según las instrucciones, en la plantilla están solo las principales: etiqueta de la tarjeta employee-card, etiqueta de dirección direction-involve y etiqueta de equipo team-qa.
Al final, después de que cada uno creó su tarjeta, se genera una tabla completa con información sobre los empleados. Esta información se puede utilizar en diferentes puntos. Los gerentes de recursos pueden armar tablas generales, y los líderes de equipos — tablas de equipo, añadiendo a la selección la etiqueta del equipo.
Por las etiquetas se pueden ver diferentes resúmenes, por ejemplo, por qa-upgrade-plan se mostrarán todas las tareas de desarrollo de QA. A su vez, cada persona en su tarjeta de empleado lleva una historia importante y su plan de desarrollo — crea una página anidada a partir de la plantilla de planes de desarrollo.
Conclusión
¡Lleva cualquier documentación de tal manera que no sea motivo de vergüenza, y que los usuarios no sientan un dolor angustiante!
Espero de verdad que el artículo sea útil y que haya orden en toda la documentación del mundo.
Fuente: habr.com
