🤽 💒 💶 Design chez Confluence 🙍🏻 🙍🏿 🕡

Bonjour à tous!

Je m'appelle Masha, je travaille comme ingénieur en assurance qualité dans le groupe d'entreprises Tinkoff. Le travail d'AQ implique beaucoup de communication avec différentes personnes de différentes équipes, et j'étais également gestionnaire et chargé de cours de programmes éducatifs, donc ma carte de communication était aussi large que possible. Et à un moment donné, j'ai explosé: j'ai réalisé que je ne pouvais plus, ne pouvais pas, ne pouvais pas remplir l'enfer de tonnes de tableaux et de documents illisibles.

Certes, chacun de vous a maintenant imaginé de quoi je parlais et a balayé la sueur froide: listes de noms de famille sans ordre alphabétique, tableaux de centaines de colonnes avec une disposition qui avait déménagé, tableaux de milliers de lignes dans lesquelles vous devez effacer votre doigt sur la molette de la souris pour voir en-tête, des tonnes de pages d'instructions non numérotées, des centaines de lettres envoyées les unes aux autres avec des données qui doivent être analysées et systématisées et insérées dans les mêmes tableaux illisibles.

Et donc, quand j'ai eu un peu froid, j'ai décidé d'écrire cet article. Je vais vous expliquer comment vous pouvez normalement (même parfois de manière pratique) gérer une variété de documentation non liée à un produit. J'espère que l'article se répandra à travers le réseau et que le niveau d'adoration dans les départements adjacents au développement diminuera même légèrement, et les gens (y compris moi-même) deviendront un peu plus heureux.

Outils

La documentation produit est souvent conservée à proximité du code, ce qui est bien. Et la documentation non-produit est généralement stockée n'importe où. Souvent, les gens essaient de transférer des informations de différents endroits vers Confluence, et nous ne faisons pas exception. Donc toute l'histoire de lui.

En général, Confluence est un moteur wiki avancé. Il vous permet de travailler avec des données dans différents types d'affichage: texte avec mise en forme, tableaux, divers diagrammes. Il s'agit d'un outil très intéressant et puissant, mais si vous ne savez pas comment le cuisiner, vous obtiendrez un autre vidage de documents illisibles. Je vais vous apprendre à cuisiner!

Macros

Presque toute la magie de Confluence est basée sur des macros. Il existe de nombreuses macros, et elles peuvent être combinées entre elles. Ils sont payants et gratuits, puis il y aura différents exemples de macros avec des liens vers la documentation pour eux.

L'interface macro est aussi simple que possible. Pour ajouter une macro, cliquez sur le plus et sélectionnez l'élément souhaité dans la liste.

Si la macro est autosuffisante, c'est-à-dire qu'elle ne nécessite pas l'insertion d'autre chose en elle-même, elle ressemble à un bloc.

Si pour que la macro fonctionne, vous devez y mettre quelque chose, cela ressemble à un cadre.

En même temps, vous pouvez mettre autant d'autres que vous le souhaitez à l'intérieur du cadre, si seulement il y a de la logique dans votre pyramide.

Chaque macro a un aperçu: elle indique immédiatement si vous avez terminé et configuré correctement la macro.

Motifs

En plus des macros, il existe un outil pratique pour préremplir le contenu - il s'agit d'un modèle.
Les modèles peuvent être utilisés lors de la création de n'importe quelle page: cliquez simplement sur les trois points à côté du bouton "Créer" et sélectionnez le modèle souhaité.

Ensuite, tout le contenu qui se trouve dans le modèle sera ajouté à la page créée.

Tout le monde peut créer des pages à partir de modèles, mais uniquement ceux qui ont le droit de créer ou de modifier eux-mêmes des modèles. Vous pouvez ajouter des instructions supplémentaires au modèle sur la façon de gérer la page.

Magie de table

En fait, en tant que technicien, j'aime beaucoup les tableaux et je peux envelopper presque toutes les informations (bien que ce ne soit pas toujours efficace). Les tableaux eux-mêmes sont clairs, structurés, évolutifs, magiques!

Mais même une entité aussi merveilleuse qu'une table peut être ruinée. Et vous pouvez utiliser et même améliorer avec succès. À ce sujet ci-dessous.

Filtrage (plugin payant)

Tout énorme tableau illisible peut être rendu un peu moins énorme et un peu plus lisible par filtrage. Pour ce faire, vous pouvez utiliser la macro payante "Filtrer les tables" .

À l'intérieur de cette macro, vous devez coller la table (vous pouvez même les plus moches, l'essentiel est de la pousser en entier). Dans la macro, vous pouvez sélectionner les colonnes du filtre avec une liste déroulante, un filtre de texte, un filtre numérique et un filtre par dates.

Imaginez simplement que toutes les informations sur les candidats pour tous les postes vacants sont enregistrées dans une liste tabulaire. Naturellement, non trié - les gens ne viennent pas pour des interviews par ordre alphabétique. Et vous devez savoir si vous avez déjà interviewé un candidat en particulier. Il vous suffit de mettre cet enfer dans la macro de filtre, d'ajouter un filtre de texte par nom de famille - et le tour est joué, les informations sur votre écran.

Il convient de noter que le filtrage d'énormes tables peut affecter le système et le temps de chargement des pages.Par conséquent, placer une énorme table dans le filtre est une béquille temporaire, il est préférable de créer un processus dans lequel les gens n'ont pas à créer d'énormes tables illisibles (un exemple du processus sera à la fin de l'article).

Trier (plugin payant)

En utilisant la macro magique «Filtre de table», vous pouvez également définir le tri par défaut par n'importe quelle colonne et numéroter les lignes. Ou cliquez sur n'importe quelle colonne du tableau qui est insérée dans la macro de filtre, et le tri par cette colonne se produira.

Par exemple, vous avez le même tableau avec les candidats et vous devez déterminer combien d'entrevues ont été menées au cours d'un mois donné - triez par date et soyez heureux.

Tableaux récapitulatifs (plugin payant)

Passons maintenant au cas le plus intéressant. Imaginez que votre table est immense et que vous devez en calculer quelque chose. Bien sûr, vous pouvez le copier dans Excel, calculer ce dont vous avez besoin et renvoyer les données vers Confluence. Ou vous pouvez appliquer la macro «Tableau croisé dynamique» une fois et obtenir le même résultat, mais également mis à jour.

Par exemple: vous avez un tableau dans lequel les données de tous les employés sont collectées - où ils se trouvent géographiquement et quels postes ils occupent. Pour calculer le nombre de personnes dans chaque ville, vous devez sélectionner dans la macro «Tableau récapitulatif» une ligne par laquelle les données (emplacement) et le type d'opération (agrégation) sont agrégés.

Naturellement, vous pouvez regrouper selon plusieurs critères à la fois, toutes les fonctionnalités peuvent être trouvées dans la documentation .

Graphiques (plugin payant)

Comme je l'ai dit, tout le monde n'aime pas les tables autant que moi. Malheureusement, la plupart d'entre eux n'aiment pas du tout les managers. Mais tout le monde aime les nuanciers colorés.
Les créateurs de Confluence, bien sûr, le savaient (ils ont probablement aussi un patron qui aime les rapports et les graphiques, mais où sans cela). Par conséquent, vous pouvez utiliser la macro magique "Graphique du tableau" . Dans cette macro, vous devez mettre le tableau croisé dynamique du paragraphe précédent, et le tour est joué - vos données grises ennuyeuses sont magnifiquement visualisées.

Naturellement, cette macro a également des paramètres. Un lien vers la documentation de n'importe quelle macro se trouve dans le mode d'édition de cette macro.

Facilité d'agrégation

Les informations contenues dans les paragraphes précédents n'étaient probablement pas une révélation pour vous. Mais maintenant, vous savez certainement comment utiliser les macros, et je peux passer à la partie la plus intéressante de l'article.

Mots clés

C'est mauvais quand les gens stockent des informations dans un article non structuré ou dans une immense table. Pire encore - lorsque certaines parties de ces informations sont non seulement illisibles, mais également dispersées à travers les étendues de Confluence. Heureusement, il est possible de collecter les informations dispersées en un seul endroit. Pour ce faire, utilisez les tags ( tags familiers à tous sur les réseaux sociaux).

Vous pouvez ajouter n'importe quel nombre de balises à n'importe quelle page. Si vous cliquez sur une balise, vous serez redirigé vers la page d'agrégation, où il y a des liens vers tous les matériaux avec cette balise, ainsi qu'avec un ensemble de balises associées. Les balises associées sont celles que l'on trouve souvent sur la même page.

Propriétés de la page

Vous pouvez ajouter une autre macro intéressante à la page pour structurer les informations - «Propriétés de la page» . À l'intérieur, vous devez soumettre un tableau de deux colonnes, la première sera la clé et la seconde sera la valeur de la propriété. De plus, la macro peut être masquée de la page afin qu'elle n'interfère pas avec la lecture du contenu, mais en même temps la page sera toujours marquée avec les touches nécessaires.

Faites attention à l'ID - il est pratique de le configurer pour accrocher différents groupes de propriétés sur différentes pages (ou même différents groupes de propriétés sur une seule page).

Rapports

Par balises, vous pouvez collecter des rapports. Par exemple, la macro de rapport de contenu collecte toutes les pages avec un ensemble spécifique de balises.

Mais un rapport plus intéressant est la macro "Rapport sur les propriétés de la page" . Il recueille également toutes les pages avec un ensemble spécifique d'étiquettes, mais n'affiche pas seulement une liste d'entre elles, mais compile un tableau (attraper le lien vers le début de l'article?), Dans quelles colonnes sont les clés des propriétés de la page.

Il se révèle un tableau récapitulatif d'informations provenant de diverses sources. C'est bien qu'il ait des fonctions pratiques: mise en page adaptative, tri par n'importe quelle colonne. En outre, un tel tableau de rapport peut être configuré dans une macro.

Lors de la configuration, vous pouvez supprimer certaines colonnes du rapport, définir l'état par défaut ou le nombre d'enregistrements affichés. Vous pouvez également définir l'ID de propriété de la page pour afficher uniquement les informations dont vous avez besoin.

Par exemple, vous avez plusieurs pages d'employés, ces pages ont un ensemble de propriétés sur une personne: quel niveau elle est, où elle est, quand elle a rejoint l'équipe, etc. Ces propriétés sont marquées par ID = employee_inf . Et il y a un deuxième ensemble de propriétés sur la même page qui recueille des informations sur la personne, en tant que membre de l'équipe: quel rôle la personne joue, dans quelle équipe elle se trouve, etc. Ces propriétés sont marquées par ID = team_inf . Ensuite, lors de l'assemblage du rapport, vous pouvez afficher uniquement des informations sur un ou deux ID à la fois, car cela est plus pratique.

La beauté de cette approche est que tout le monde peut collecter le tableau d'informations dont il a besoin, qui ne dupliquera rien et sera mis à jour lorsque la page principale sera mise à jour. Par exemple: Timlidu n'est pas important lorsque ses développeurs ont obtenu un emploi, mais il est important de savoir quel rôle chacun d'eux joue dans l'équipe. Timlid collectera un rapport sur l'équipe. Et le comptable ne se soucie pas de savoir qui remplit quel rôle, mais les postes sont importants - il collectera un rapport sur les postes. Dans ce cas, la source d'informations ne sera pas dupliquée ou transférée.

Processus final

Manuel d'instructions

Ainsi, nous pouvons magnifiquement structurer et agréger efficacement des informations dans Confluence en utilisant des macros comme exemple. Mais idéalement, il faut s'assurer que la nouvelle information est immédiatement structurée et rentre dans tous les mécanismes d'agrégation déjà utilisés.

Ici, un tas de macros et de modèles viendront à la rescousse. Pour que les gens créent de nouvelles pages au bon format, vous pouvez utiliser la macro "Créer à partir d'un modèle". Il ajoute un bouton à la page, en cliquant sur lequel une nouvelle page est créée à partir du modèle dont vous avez besoin. Ainsi, vous faites travailler immédiatement les gens dans le format dont vous avez besoin.

Dans le modèle à partir duquel vous créez une page, vous devez ajouter des étiquettes, la macro «Propriétés de la page» et un tableau des propriétés dont vous avez besoin à l'avance. Je recommande également d'ajouter des instructions sur les valeurs qui doivent remplir la page et les valeurs des propriétés.

Ensuite, le processus final ressemblera à ceci:

Vous créez un modèle pour les informations d'un certain type.
Ajoutez des balises et des propriétés de page dans la macro à ce modèle.
Dans un endroit pratique, créez une page racine avec un bouton, en cliquant sur laquelle une page enfant du modèle est créée.
Lancez sur la page racine des utilisateurs qui généreront potentiellement les informations nécessaires (selon le modèle souhaité, en cliquant sur le bouton).
Rassemblez un rapport sur les propriétés de la page via les étiquettes que vous avez spécifiées dans le modèle.
Réjouissez-vous: vous avez toutes les informations nécessaires dans un format pratique.

Roches sous-marines

En tant qu'ingénieur qualité, je peux dire en toute sécurité qu'il n'y a rien d'idéal dans le monde. Même les tables divines sont imparfaites. Et dans le processus ci-dessus, il y a des pièges.

Si vous décidez de modifier le nom ou la composition des propriétés de la page, vous devrez mettre à jour tous les objets déjà créés afin que leurs données soient correctement extraites dans le rapport de synthèse. C'est triste, mais d'un autre côté, cela vous fait réfléchir en détail à «l'architecture» de votre ensemble d'informations, ce qui est une tâche très intéressante.
Vous devrez rédiger une quantité décente d'instructions sur la façon de remplir les tableaux d'informations et d'utiliser les balises. Mais, d'autre part, vous pouvez simplement jeter toutes les bonnes personnes dans cet article.

Un exemple de stockage de documentation non-produit

Grâce au processus décrit ci-dessus, vous pouvez organiser le stockage de presque toutes les informations. La beauté de l'approche est qu'elle est universelle: lorsque les utilisateurs s'y habituent, ils cessent de générer un gâchis. Un autre avantage important (mais non gratuit) est la possibilité de collecter diverses statistiques à la volée et de dessiner de beaux diagrammes dessus.

Je vais donner un exemple de notre processus de conservation des informations sur l'équipe.

Pour chaque personne de l'équipe, nous avons décidé de créer une carte d'employé. En conséquence, nous avons un modèle selon lequel chaque nouvelle personne crée cette carte pour elle-même et y conserve toutes les informations personnelles.

Comme vous pouvez le voir, nous avons un tableau détaillé des propriétés et avons immédiatement des instructions sur la façon de maintenir cette page. Certaines étiquettes sont posées par les employés eux-mêmes conformément aux instructions, dans le modèle uniquement les principales: étiquette de cartecarte d'employé , étiquette de direction -direction et étiquette d' équipe-qa .

En conséquence, après que chacun a créé une carte pour lui-même, un tableau complet contenant des informations sur les employés est obtenu. Ces informations peuvent être utilisées à différents points. Les gestionnaires de ressources peuvent collecter eux-mêmes des tableaux généraux et les chefs d'équipe peuvent créer des tableaux d'équipe en ajoutant une balise d'équipe à la sélection.

Vous pouvez voir différents résumés par balises, par exemple, par qa-upgrade-plan toutes les tâches pour le développement QA seront affichées. Dans le même temps, chaque personne sur sa carte d'employé mène une histoire importante et son plan de développement - crée une page intégrée à partir du modèle de plans de développement.

Conclusion

Conservez toute documentation afin qu'elle ne soit pas gênante et que les utilisateurs ne soient pas atrocement blessés!

J'espère vraiment que l'article sera utile et que toute la documentation du monde sera en ordre.

Design chez Confluence