🧙🏿 ☯️ 🚰 Diseño en Confluence 🎢 🛀🏼 🐣

¡Hola a todos!

Mi nombre es Masha, trabajo como ingeniero de garantía de calidad en el grupo de empresas Tinkoff. El trabajo de control de calidad implica mucha comunicación con diferentes personas de diferentes equipos, y también fui gerente y profesor de programas educativos, por lo que mi mapa de comunicación fue lo más amplio posible. Y en algún momento exploté: me di cuenta de que ya no podía, no podía, no podía llenar el infierno de toneladas de tablas y documentos ilegibles.

Seguramente cada uno de ustedes imaginaba de lo que estaba hablando y sudaba frío: listas de apellidos sin orden alfabético, tablas de cientos de columnas con un diseño que se había movido, tablas de miles de líneas en las que necesita borrar el dedo en la rueda del mouse para mirar encabezado, toneladas de páginas de instrucciones no numeradas, cientos de cartas enviadas entre sí con datos que deben analizarse y sistematizarse y guardarse en las mismas tablas ilegibles.

Entonces, cuando tuve un poco de frío, decidí escribir este artículo. Hablaré sobre cómo puede mantener normalmente (incluso a veces convenientemente) una variedad de documentación que no es del producto. Espero que el artículo se extienda por toda la red y el nivel de admiración en los departamentos adyacentes al desarrollo disminuirá incluso un poco, y las personas (incluido yo mismo) se sentirán un poco más felices.

Herramientas

La documentación del producto a menudo se mantiene cerca del código, lo cual es bueno. Y la documentación que no es del producto generalmente se almacena en cualquier lugar. A menudo las personas intentan transferir información de diferentes lugares a Confluence, y no somos una excepción. Entonces, toda la historia sobre él.

En general, Confluence es un motor wiki avanzado. Le permite trabajar con datos en diferentes tipos de visualización: texto con formato, tablas, una variedad de diagramas. Esta es una herramienta muy interesante y poderosa, pero si no sabe cómo cocinarla, obtendrá otro volcado de documentos ilegibles. ¡Te enseñaré a cocinar!

Macros

Casi toda la magia de Confluence está construida sobre macros. Hay muchas macros y se pueden combinar entre sí. Son de pago y gratuitos, entonces habrá diferentes ejemplos de macros con enlaces a la documentación para ellos.

La interfaz macro es lo más simple posible. Para agregar una macro, haga clic en el signo más y seleccione el elemento deseado de la lista.

Si la macro es autosuficiente, es decir, no requiere la inserción de otra cosa dentro de sí misma, se ve como un bloque.

Si para que la macro funcione, necesita poner algo dentro de ella, parece un marco.

Al mismo tiempo, puede poner tantos otros como desee dentro del marco, si solo hay lógica en su pirámide.

Cada macro tiene una vista previa: muestra inmediatamente si ha completado y configurado la macro correctamente.

Patrones

Además de las macros, existe una herramienta conveniente para rellenar previamente el contenido: esta es una plantilla.
Las plantillas se pueden usar al crear cualquier página: simplemente haga clic en los tres puntos al lado del botón "Crear" y seleccione la plantilla deseada.

Luego, todo el contenido que está en la plantilla se agregará a la página creada.

Cualquiera puede crear páginas a partir de plantillas, pero solo aquellos que tienen derecho a crear o editar plantillas ellos mismos. Puede agregar instrucciones adicionales a la plantilla sobre cómo mantener la página.

Magia de mesa

En realidad, como técnico, me encantan las tablas y puedo incluir casi cualquier información en ellas (aunque esto no siempre es efectivo). ¡Las tablas en sí son claras, estructuradas, escalables, mágicas!

Pero incluso una entidad tan maravillosa como una mesa puede arruinarse. Y puede usar con éxito e incluso mejorar. Sobre esto a continuación.

Filtrado (complemento pagado)

Cualquier tabla enorme ilegible se puede hacer un poco menos grande y un poco más legible mediante el filtrado. Para hacer esto, puede usar la macro paga "Filtrar tablas" .

Dentro de esta macro, debes pegar la tabla (puedes incluso lo más feo, lo principal es empujarla por completo). En la macro, puede seleccionar las columnas para el filtro con una lista desplegable, un filtro de texto, un filtro numérico y un filtro por fechas.

Imagine que toda la información sobre los candidatos para todas las vacantes se registra en una lista tabular. Naturalmente, sin clasificar: las personas no acuden a las entrevistas alfabéticamente. Y debe comprender si ha entrevistado a un solicitante de empleo en particular antes. Solo necesita poner este infierno en la macro del filtro, agregar un filtro de texto por apellido y listo, la información en su pantalla.

Vale la pena señalar que filtrar tablas enormes puede afectar el sistema y el tiempo de carga de la página, por lo que poner una tabla enorme en el filtro es una muleta temporal, es mejor construir un proceso en el que las personas no tengan que crear tablas indescifrables enormes (un ejemplo del proceso estará al final del artículo).

Ordenar (complemento pagado)

Usando la macro mágica "Filtro de tabla" también puede establecer la clasificación predeterminada por cualquier columna y numerar las filas. O haga clic en cualquier columna de la tabla que aparezca en la macro de filtro, y se ordenará por esta columna.

Por ejemplo, tiene la misma tabla con los solicitantes y necesita calcular cuántas entrevistas se llevaron a cabo en un mes en particular: ordene por fecha y sea feliz.

Tablas de resumen (complemento pagado)

Ahora pasemos al caso más interesante. Imagine que su tabla es enorme y necesita calcular algo a partir de ella. Por supuesto, puede copiarlo en Excel, calcular lo que necesita y cargar los datos nuevamente en Confluence. O puede aplicar la macro "Tabla dinámica" una vez y obtener el mismo resultado, pero también actualizado.

Por ejemplo: tiene una tabla en la que se recopilan los datos de todos los empleados, dónde se ubican geográficamente y qué puestos ocupan. Para calcular cuántas personas hay en cada ciudad, debe seleccionar en la macro "Tabla de resumen" una línea por la cual se agregan los datos (ubicación) y el tipo de operación (agregación).

Naturalmente, puede agrupar por varios criterios a la vez, todas las características se pueden encontrar en la documentación .

Gráficos (complemento pagado)

Como dije, no a todos les gustan las mesas tanto como a mí. Desafortunadamente, a la mayoría de ellos no les gustan los gerentes en absoluto. Pero a todos les encantan las cartas de colores vibrantes.
Los creadores de Confluence, por supuesto, sabían sobre esto (probablemente también tienen un jefe al que le encantan los informes y gráficos, pero sin ellos). Por lo tanto, puede usar la macro mágica "Gráfico de la tabla" . En esta macro, debe colocar la tabla dinámica del párrafo anterior y listo, sus datos aburridos grises se visualizan maravillosamente.

Naturalmente, esta macro también tiene configuraciones. Se puede encontrar un enlace a la documentación de cualquier macro en el modo de edición de esta macro.

Facilidad de agregación

La información en los párrafos anteriores probablemente no fue una revelación para usted. Pero ahora definitivamente sabe cómo usar macros, y puedo pasar a la parte más interesante del artículo.

Etiquetas

Es malo cuando las personas almacenan información en un artículo no estructurado o en una tabla enorme. Peor aún, cuando partes de esta información no solo son ilegibles, sino que también están dispersas en las extensiones de Confluence. Afortunadamente, existe la oportunidad de recopilar la información dispersa en un solo lugar. Para hacer esto, use las etiquetas ( etiquetas familiares para todos en las redes sociales).

Puede agregar cualquier cantidad de etiquetas a cualquier página. Si hace clic en una etiqueta, se lo dirigirá a la página de agregación, donde hay enlaces a todos los materiales con esta etiqueta, así como con un conjunto de etiquetas relacionadas. Las etiquetas relacionadas son aquellas que a menudo se encuentran en la misma página.

Propiedades de la página

Puede agregar otra macro interesante a la página para estructurar la información: "Propiedades de la página" . En su interior, debe enviar una tabla de dos columnas, la primera será la clave y la segunda será el valor de la propiedad. Además, la macro se puede ocultar de la página para que no interfiera con la lectura del contenido, pero al mismo tiempo la página seguirá marcada con las teclas necesarias.

Preste atención a la ID: es conveniente configurarla para colgar diferentes grupos de propiedades en diferentes páginas (o incluso diferentes grupos de propiedades en una página).

Informes

Por etiquetas, puede recopilar informes. Por ejemplo, la macro Informe de contenido recopila todas las páginas con un conjunto específico de etiquetas.

Pero un informe más interesante es la macro "Informe de propiedades de página" . También recopila todas las páginas con un conjunto específico de etiquetas, pero no solo muestra una lista de ellas, sino que compila una tabla (¿capta el enlace al comienzo del artículo?), ¿En qué columnas están las claves de las propiedades de la página?

Resulta una tabla resumen de información de varias fuentes. Es bueno que tenga funciones convenientes: diseño adaptativo, clasificación por cualquier columna. Además, dicha tabla de informes se puede configurar dentro de una macro.

Al configurar, puede eliminar algunas columnas del informe, establecer el estado predeterminado o la cantidad de registros que se muestran. También puede establecer el ID de propiedad de la página para ver solo la información que necesita.

Por ejemplo, tiene muchas páginas de empleados, estas páginas tienen un conjunto de propiedades sobre una persona: en qué nivel se encuentra, dónde se encuentra, cuándo se unió al equipo, etc. Estas propiedades están marcadas con 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é papel desempeña la persona, en qué equipo está, y así sucesivamente. Estas propiedades están marcadas con ID = team_inf . Luego, al armar el informe, puede mostrar solo información sobre una ID o solo dos a la vez, ya que es más conveniente.

La belleza de este enfoque es que todos pueden recopilar la tabla de información que necesitan, que no duplicará nada y se actualizará cuando se actualice la página principal. Por ejemplo: Timlidu no es importante cuando sus desarrolladores consiguieron un trabajo, pero es importante qué papel juegan cada uno de ellos en el equipo. Timlid recopilará un informe sobre el equipo. Y al contador no le importa quién desempeña qué función, pero las publicaciones son importantes: recopilará un informe sobre las publicaciones. En este caso, la fuente de información no se duplicará ni transferirá.

Proceso final

Manual de instrucciones

Entonces, podemos estructurar bellamente y agregar eficientemente información en Confluence usando macros como ejemplo. Pero, idealmente, es necesario asegurarse de que la nueva información esté estructurada de inmediato y se encuentre en todos los mecanismos de agregación ya utilizados.

Aquí un montón de macros y plantillas vendrán al rescate. Para que las personas creen nuevas páginas en el formato correcto, puede usar la macro "Crear desde plantilla". Agrega un botón a la página, al hacer clic en el cual se crea una nueva página a partir de la plantilla que necesita. Por lo tanto, hace que las personas trabajen inmediatamente en el formato que necesita.

En la plantilla desde la que está creando una página, debe agregar etiquetas, la macro "Propiedades de la página" y una tabla de las propiedades que necesita de antemano. También recomiendo agregar instrucciones sobre qué valores deben llenar la página y los valores de propiedad.

Entonces el proceso final se verá así:

Crea una plantilla para información de un tipo determinado.
Agregue etiquetas y propiedades de página en la macro a esta plantilla.
En cualquier lugar conveniente, cree una página raíz con un botón, haciendo clic en qué página secundaria se crea a partir de la plantilla.
Inicie en la página raíz de usuarios que potencialmente generarán la información necesaria (de acuerdo con la plantilla deseada, haciendo clic en el botón).
Reúna un informe sobre las propiedades de la página a través de las etiquetas que especificó en la plantilla.
Alégrate: tienes toda la información necesaria en un formato conveniente.

Rocas bajo el agua

Como ingeniero de calidad, puedo decir con seguridad que no hay nada ideal en el mundo. Incluso las mesas divinas son imperfectas. Y en el proceso anterior, hay dificultades.

Si decide cambiar el nombre o la composición de las propiedades de la página, deberá actualizar todos los objetos ya creados para que sus datos se tomen correctamente en el informe resumido. Esto es triste, pero, por otro lado, te hace pensar en la "arquitectura" de tu conjunto de información en detalle, lo cual es una tarea muy interesante.
Tendrá que escribir una cantidad decente de instrucciones sobre cómo completar tablas de información y usar etiquetas. Pero, por otro lado, puedes incluir a todas las personas adecuadas en este artículo.

Un ejemplo de almacenamiento de documentación no relacionada con el producto.

A través del proceso descrito anteriormente, puede organizar el almacenamiento de casi cualquier información. La belleza del enfoque es que es universal: cuando los usuarios se acostumbran, dejan de generar un desastre. También una gran ventaja (pero no gratuita) es la capacidad de recopilar varias estadísticas sobre la marcha y dibujar hermosos diagramas en él.

Daré un ejemplo de nuestro proceso de mantener información sobre el equipo.

Para cada persona en el equipo, decidimos crear una tarjeta de empleado. En consecuencia, tenemos una plantilla según la cual cada persona nueva crea esta tarjeta para sí mismo y mantiene toda la información personal en ella.

Como puede ver, tenemos una tabla detallada de propiedades e inmediatamente tenemos instrucciones sobre cómo mantener esta página. Algunas de las etiquetas son colocadas por los propios empleados de acuerdo con las instrucciones, en la plantilla solo las principales: etiqueta de tarjetaempleado-tarjeta , dirección etiqueta -dirección y equipo de control de calidad etiqueta .

Como resultado, después de que todos hayan creado una tarjeta para ellos, se obtiene una tabla completa con información sobre los empleados. Esta información se puede usar en varios puntos. Los administradores de recursos pueden recopilar tablas generales para ellos, y los líderes de equipo pueden crear tablas de equipo agregando una etiqueta de equipo a la selección.

Puede ver diferentes resúmenes por etiquetas, por ejemplo, por qa-upgrade-plan , se mostrarán todas las tareas para el desarrollo del control de calidad. Al mismo tiempo, cada persona en su tarjeta de empleado lidera una historia importante y su plan de desarrollo: crea una página incrustada a partir de la plantilla para los planes de desarrollo.

Conclusión

¡Guarde toda la documentación para que no resulte vergonzoso y los usuarios no sufran daños insoportables!

Realmente espero que el artículo sea útil y que toda la documentación del mundo esté en orden.

Diseño en Confluence