Bonjour à tous!
Je m'appelle Masha, je travaille comme ingénieur en assurance qualité dans le groupe d'entreprises Tinkoff. Le travail d'assurance qualité implique beaucoup de communication avec différentes personnes de différentes équipes, et j'étais également responsable et enseignant 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 peux plus, je ne peux plus, je ne peux plus remplir des tonnes infernales de tableaux et de documents illisibles.
Chacun d'entre vous a sûrement maintenant imaginé de quoi je parle et a eu des sueurs froides : des listes de noms de famille sans ordre alphabétique, des tableaux avec des centaines de colonnes avec une disposition bâclée, des tableaux avec des milliers de lignes dans lesquelles vous devez effacer votre doigt sur la molette de la souris pour regarder l'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 fourrées dans les mêmes tableaux illisibles.
Et donc, quand je me suis un peu calmé, j'ai décidé d'écrire cet article. Je vais parler de la façon dont vous pouvez normalement (même parfois commodément) maintenir une variété de documentation non-produit. J'espère que l'article se dispersera sur le réseau et que le niveau d'enfer dans les départements adjacents au développement baissera au moins un peu, et que les gens (y compris moi) deviendront un peu plus heureux.
Outils
La documentation du produit est souvent conservée avec le code, ce qui est une bonne chose. Et la documentation non liée au produit est généralement stockée n'importe où. Souvent, les gens essaient d'apporter des informations de différents endroits dans Confluence, et nous ne faisons pas exception. Donc le reste de l'histoire est à son sujet.
En général, Confluence est un moteur wiki avancé. Il permet de travailler avec des données dans différents types d'affichage : texte avec mise en forme, tableaux, graphiques divers. C'est un outil très intéressant et puissant, mais si vous ne savez pas comment le cuisiner, vous obtiendrez une autre décharge de documents illisibles. Je vais t'apprendre à cuisiner !
macros
Presque toute la magie de Confluence est construite autour des macros. Il existe de nombreuses macros et elles peuvent être combinées entre elles. Ils sont payants et gratuits, en outre, il y aura divers exemples de macros avec des liens vers leur documentation.
L'interface pour travailler avec les macros est aussi simple que possible. Pour ajouter une macro, vous devez cliquer sur le plus et sélectionner 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 à l'intérieur d'elle-même, elle ressemble à un bloc.
Si une macro a besoin de quelque chose à l'intérieur pour fonctionner, elle ressemble à une boîte.
En même temps, vous pouvez en mettre autant d'autres que vous le souhaitez dans un même cadre, tant qu'il y a de la logique dans votre pyramide.
Chaque macro a un aperçu : il indique immédiatement si vous avez correctement rempli et configuré la macro.
Modèles
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 du modèle sera ajouté à la page créée.
N'importe qui peut créer des pages à partir de modèles, mais seuls ceux qui ont le droit de créer ou de modifier eux-mêmes des modèles peuvent créer des pages. Vous pouvez ajouter des instructions supplémentaires au modèle sur la façon dont la page doit être maintenue.
Tableau magique
En fait, en tant que technophile, j'adore les tableaux et je peux y insérer 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 gâchée. Et il peut être utilisé avec succès et même amélioré. Plus à ce sujet ci-dessous.
Filtrage (plugin payant)
Toute grande table illisible peut être rendue un peu moins grande et un peu plus lisible en utilisant le filtrage. Pour ce faire, vous pouvez utiliser une macro payante .
À l'intérieur de cette macro, vous devez enfoncer une table (même la plus laide est possible, l'essentiel est de l'enfoncer entièrement). Dans la macro, vous pouvez sélectionner des colonnes pour le filtre déroulant, le filtre de texte, le filtre numérique et le filtre de date.
Imaginez simplement que toutes les informations sur les candidats pour tous les postes vacants soient enregistrées dans une liste tabulaire. Naturellement, non triés - les gens ne viennent pas aux entretiens par ordre alphabétique. Et vous devez comprendre si vous avez déjà interviewé un candidat spécifique. Il vous suffit de mettre cet enfer dans une macro de filtrage, d'ajouter un filtre de texte par nom de famille - et le tour est joué, l'information est sur votre écran.
Il convient de noter que le filtrage d'énormes tables peut affecter les performances du système et le temps de chargement des pages, donc mettre une énorme table dans le filtre est une béquille temporaire, il est préférable de construire 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).
Tri (plugin payant)
Avec macro magique vous pouvez également définir le tri par défaut sur n'importe quelle colonne et numéroter les lignes. Ou cliquez sur n'importe quelle colonne de la table placé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'entretiens ont eu lieu au cours d'un mois donné - triez par date et réjouissez-vous.
Tableaux croisés dynamiques (plugin payant)
Passons maintenant à un cas plus intéressant. Imaginez que votre table est énorme et que vous devez calculer quelque chose dessus. Bien sûr, vous pouvez le copier dans Excel, calculer ce dont vous avez besoin et télécharger les données dans Confluence. Pouvez-vous appliquer une macro une fois ? et obtenir le même résultat, seulement mis à jour.
Par exemple : vous avez un tableau qui contient les données de tous les employés - 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 croisé dynamique" la ligne par laquelle les données sont agrégées (localisation) et le type d'opération (addition).
Naturellement, vous pouvez regrouper selon plusieurs critères à la fois, vous pouvez voir toutes les possibilités .
Graphiques (plugin payant)
Comme je l'ai dit, tout le monde n'aime pas les tables autant que moi. Malheureusement, la plupart des managers ne les aiment pas du tout. Mais tout le monde aime les nuanciers de couleurs vives.
Les créateurs de Confluence le savaient certainement (il est certain qu'ils ont aussi des patrons qui aiment les rapports et les graphiques, où en seraient-ils sans cela). Par conséquent, vous pouvez utiliser la macro magique . 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 peut être trouvé dans le mode d'édition de cette macro.
Facilité d'agrégation
Les informations des paragraphes précédents n'ont probablement pas été 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 un immense tableau. Pire encore, lorsque certaines parties de ces informations sont non seulement illisibles, mais également dispersées dans les étendues de Confluence. Heureusement, il est possible de collecter des informations dispersées en un seul endroit. Pour cela, vous devez utiliser (tags connus de tous sur les réseaux sociaux).
N'importe quel nombre de balises peut être ajouté à n'importe quelle page. Cliquer sur une balise vous amènera à une page d'agrégation avec des liens vers tout le contenu avec cette balise, ainsi qu'un ensemble de balises associées. Les balises associées sont celles qui apparaissent fréquemment 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 - . À l'intérieur, vous devez soumettre un tableau de deux colonnes, la première sera la clé et la seconde 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 la page sera toujours marquée avec les clés 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 page).
Rapports
Par balises, vous pouvez collecter des rapports. Par exemple, macro collecte toutes les pages avec un certain ensemble de balises.
Mais un rapport plus intéressant est une macro . Il collecte également toutes les pages avec un certain ensemble de balises, mais ne se contente pas de les répertorier, mais compile un tableau (attrapez-vous le lien avec le début de l'article ?), Dans lequel les colonnes sont les clés des propriétés de la page.
Il s'avère un tableau récapitulatif des informations provenant de différentes sources. C'est bien qu'il ait des fonctionnalités pratiques : mise en page adaptative, tri par n'importe quelle colonne. En outre, un tel tableau de rapport peut être configuré à l'intérieur de la 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 beaucoup de pages d'employés, ces pages ont un ensemble de propriétés sur une personne : quel niveau il est, où il se trouve, quand il a rejoint l'équipe, etc. Ces propriétés sont marquées id = employé_inf. Et il y a un deuxième ensemble de propriétés sur la même page, qui contient des informations sur une personne dans le cadre d'une équipe : quel rôle la personne joue, dans quelle équipe elle fait partie, etc. Ces propriétés sont marquées ID = team_inf. Ensuite, lors de la compilation d'un rapport, vous pouvez afficher uniquement les informations pour un ou deux ID à la fois, selon ce qui est le plus pratique.
La beauté de cette approche est que chacun peut collecter le tableau d'informations dont il a besoin, qui ne dupliquera rien et sera mis à jour lors de la mise à jour de la page principale. Par exemple : un chef d'équipe ne se soucie pas du moment où ses développeurs ont obtenu un emploi, mais il est important de savoir quel rôle chacun d'eux joue dans l'équipe. Le chef d'équipe recueillera un rapport sur l'équipe. Et le comptable ne se soucie pas de savoir qui joue quel rôle, mais les postes sont importants - il recueillera un rapport sur les postes. Dans ce cas, la source d'information ne sera ni dupliquée ni transférée.
Processus final
Instruction
Ainsi, nous pouvons magnifiquement structurer et agréger efficacement les informations dans Confluence en utilisant des macros comme exemple. Mais idéalement, vous devez vous assurer que les nouvelles informations sont immédiatement structurées et pénètrent 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 amener les gens à créer de nouvelles pages dans le 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. De cette façon, vous forcez les gens à travailler immédiatement dans le format dont vous avez besoin.
Dans le modèle à partir duquel vous autorisez la création d'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 avec lesquelles remplir la page et les valeurs de propriété.
Ensuite, le processus final ressemblera à ceci :
- Vous créez un modèle pour un type spécifique d'informations.
- Dans ce modèle, ajoutez des étiquettes et des propriétés de page dans une macro.
- Dans n'importe quel endroit pratique, créez une page racine avec un bouton, en cliquant sur lequel une page enfant est créée à partir du modèle.
- Lancez-vous 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).
- Recueillez-vous un rapport sur les propriétés de la page grâce aux balises que vous avez spécifiées dans le modèle.
- Réjouissez-vous : vous disposez de toutes les informations dont vous avez besoin dans un format pratique.
Pièges
En tant qu'ingénieur qualité, je peux dire en toute sécurité qu'il n'y a rien de parfait dans le monde. Même les tables divines sont imparfaites. Et il y a des pièges dans le processus ci-dessus.
- Si vous décidez de modifier les noms 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 oblige à réfléchir en détail sur "l'architecture" de votre ensemble d'informations, ce qui est une tâche très intéressante.
- Vous devrez écrire une quantité décente d'instructions sur la façon de remplir les tableaux d'informations et d'utiliser les balises. Mais, d'un autre côté, vous pouvez simplement lancer cet article à toutes les bonnes personnes.
Un exemple de stockage de documentation non liée au 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 : une fois que les utilisateurs s'y sont habitués, ils cessent de faire des dégâts. Un autre gros avantage (mais pas gratuit) est la possibilité de collecter diverses statistiques à la volée et d'y dessiner de beaux diagrammes.
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 ses 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 des étiquettes sont posées par les employés eux-mêmes selon les instructions, dans le modèle uniquement les principales : l'étiquette de la carte carte-employé, balise de direction direction-impliquer et balise de commande équipe-qa.
En conséquence, après que chacun a créé une carte pour lui-même, un tableau complet avec des informations sur les employés est obtenu. Ces informations peuvent être utilisées à différents moments. Les gestionnaires de ressources peuvent collecter des tableaux généraux pour eux-mêmes et les chefs d'équipe peuvent collecter des tableaux de commandes en ajoutant une balise d'équipe à la sélection.
Par balises, vous pouvez voir différents résumés, par exemple, par plan-de-mise à niveau-qa toutes les tâches de développement QA seront affichées. Dans le même temps, chaque personne dans sa carte d'employé conserve une histoire importante et son propre plan de développement - il crée une page imbriquée à partir du modèle de plans de développement.
Conclusion
Conservez toute documentation de manière à ce que vous n'en ayez pas honte et que les utilisateurs ne soient pas atrocement blessés !
J'espère vraiment que l'article sera utile et que l'ordre viendra dans toute la documentation du monde.
Source: habr.com