🥇Design i Confluence

Hej alle sammen!

Mit navn er Masha, jeg arbejder som QA-ingeniør i Tinkoff Group. QA-arbejde involverer mange kommunikationer med forskellige personer fra forskellige teams, og da jeg også har været leder og underviser i uddannelsesprogrammer, var mit kommunikationsnetværk meget omfattende. Og på et tidspunkt eksploderede jeg: jeg indså, at jeg ikke længere kunne, kunne ikke, kunne ikke udfylde de uendelige mængder ulæselige tabeller og dokumenter.

Sikkert har hver af jer lige nu forestillet sig det, jeg taler om, og fået sved på panden: navnelister uden alfabetisk rækkefølge, tabeller med hundrede kolonner og forskudt layout, tabeller med tusindvis af rækker, hvor man skal gnide fingeren mod musens hjul for at se overskriften, tonvis af ikke-nummererede instruktioner, hundrede e-mails der sendes frem og tilbage med data, der skal analyseres og systematiseres og presses ind i lige så ulæselige tabeller.

Og når jeg nu var lidt kølet ned, besluttede jeg at skrive denne artikel. Jeg vil fortælle om, hvordan man kan føre forskellig ikke-produktdokumentation ordentligt (nogle gange endda bekvemt). Jeg håber, at artiklen vil sprede sig på nettet, og at niveauet af kaos i de nabointeresserede afdelinger til udviklingen vil falde en smule, så folk (og jeg selv) bliver lidt lykkeligere.

Værktøjer

Produktdokumentation opbevares ofte tæt på koden, hvilket er godt. Ikke-produktdokumentation opbevares derimod ofte hvor som helst. Folk forsøger ofte at overføre information fra forskellige steder til Confluence, og vi er ingen undtagelse. Så alt videre handler om det.

Generelt er Confluence en avanceret wiki-motor. Den tillader arbejde med data i forskellige visningsformer: tekst med formatering, tabeller, forskellige diagrammer. Det er et meget interessant og kraftfuldt værktøj, men hvis man ikke ved, hvordan man forbereder det, ender man med en bunke ulæselige dokumenter. Jeg vil lære dig at forberede det!

Makroer

Næsten al magi i Confluence bygger på makroer. Der er mange makroer, og de kan kombineres med hinanden. De findes i både betalte og gratis versioner, og følgende vil være forskellige eksempler på makroer med links til dokumentationen for dem.

Grænsefladen til at arbejde med makroer er meget enkel. For at tilføje en makro skal man klikke på plusset og vælge den ønskede element fra listen.

Hvis makroen er selvforsynende, det vil sige, at den ikke kræver indsættelse af noget indeni sig selv, ser den ud som en blok.

Hvis makroen har brug for, at der bliver placeret noget indeni den, ser den ud som en ramme.

Man kan dog placere så mange andre inde i én ramme, som man vil, så længe der er logik i din pyramide.

Hver makro har en forhåndsvisning: Her kan du straks se, om du har udfyldt og indstillet makroen korrekt.

Skabeloner

Udover makroer er der et praktisk værktøj til forudfyldning af indhold – det er en skabelon.
Skabeloner kan bruges, når du opretter enhver side: du skal blot klikke på de tre prikker ved siden af knappen ‘Opret’ og vælge den ønskede skabelon.

Så vil al indholdet fra skabelonen blive tilføjet til den oprettede side.

Alle kan oprette sider ud fra skabeloner, men kun de, der har rettigheder, kan oprette eller redigere selve skabelonerne. I skabelonen kan der tilføjes yderligere instruktioner om, hvordan siden skal håndteres.

Magien ved tabeller

Som tekniker elsker jeg faktisk tabeller og kan næsten pakke enhver information ind i dem (selvom det ikke altid er effektivt). Tabeller i sig selv er klare, strukturerede, skalerbare, magiske!

Men selv en så vidunderlig enhed som en tabel kan blive ødelagt. Men den kan også bruges effektivt og endda forbedres. Det handler om nedenfor.

Filtrering (betalt plugin)

Enhver stor, uoverskuelig tabel kan gøres lidt mindre enorm og lidt mere læsbar med hjælp fra filtrering. Til dette kan man bruge en betalt makro. ‘Tabelfilter’.

Ind i denne makro skal tabelen presses (man kan endda bruge den mest grimme, så længe den presses helt ind). I makroen kan du vælge kolonner til filtrering med en drop-down liste, tekstfilter, numerisk filter og datofilter.

Forestil dig, at al information om kandidater til alle job skrives i en tabellist. Selvfølgelig usorteret – folk kommer jo ikke til samtaler i alfabetisk rækkefølge. Og du skal finde ud af, om du tidligere har afholdt en samtale med en bestemt ansøger. Du skal bare presse dette kaos ind i filtreringsmakroen, tilføje et tekstfilter efter efternavn – og vupti, så har du informationen på din skærm.

Det skal bemærkes, at filtrering af store tabeller kan påvirke systemets ydeevne og indlæsningstider, så det er en midlertidig løsning at putte en enorm tabel i et filter; det er bedre at opbygge en proces, hvor folk ikke behøver at lave enorme, ulæselige tabeller (et eksempel på processen vil være i slutningen af artiklen).

Sortering (betalt plugin)

Ved hjælp af et magisk makro ‘Tabelfilter’ kan man også angive standard sortering på hvilken som helst kolonne og nummerere rækkerne. Eller klikke på en hvilken som helst kolonne i tabellen, der er lagt ind i filtermakroen, og sortering vil ske på denne kolonne.

For eksempel, hvis du har den samme tabel med ansøgere og skal vurdere, hvor mange interviews der er blevet afholdt i en bestemt måned, - så sorter efter dato og vær glad.

Pivot-tabeller (betalt plugin)

Lad os nu gå videre til en mere interessant case. Forestil dig, at din tabel er enorm, og du skal regne noget ud. Selvfølgelig kan du kopiere den over i Excel, beregne det nødvendige og eksporter dataene tilbage til Confluence. Men du kan også en gang for alle anvende makroen "Pivot-tabel" og få det samme resultat, kun opdateret.

For eksempel: du har en tabel, der indeholder oplysninger om alle medarbejdere - hvor de geografisk befinder sig, og hvilke stillinger de har. For at tælle, hvor mange personer der er i hver by, skal du vælge i makroen "Pivot-tabel" den række, som dataene aggregeres efter (placering) og type operation (summering).

Naturligvis kan man gruppere efter flere kriterier på én gang; alle muligheder kan ses i dokumentationen.

Diagrammer (betalt plugin)

Som jeg allerede har nævnt, elsker ikke alle tabeller lige så meget som jeg. Desværre kan managerne i de fleste tilfælde slet ikke lide dem. Men alle elsker klart farverige diagrammer.
Skaberne af Confluence vidste uden tvivl om dette (de har sikkert også chefer, der elsker rapporter og diagrammer, hvor skulle de ellers hen). Derfor kan du bruge det magiske makro "Diagram fra tabel". I dette makro skal du indsætte den pivot-tabel fra det forrige punkt, og vupti - dine grå, kedelige data er smukt visualiseret.

Naturligvis er der også indstillinger i dette makro. Linket til dokumentationen til ethvert makro kan findes i redigeringsmodus for dette makro.

Simplicity in aggregation

Information from the previous sections was certainly not a revelation for you. But now you definitely know how to use macros, and I can move on to a more interesting part of the article.

Labels

It's unfortunate when people store information in one unstructured article or a huge table. Even worse is when parts of that information are not only poorly formatted but also scattered across the vastness of Confluence. Fortunately, there is a way to gather the scattered information in one place. To do this, you need to use tags (familiar to everyone from social media tags).

You can add any number of tags to any page. If you click on a tag, you will be taken to an aggregation page that contains links to all materials with that tag, as well as a set of related tags. Related tags are those that often appear on the same page.

Page properties

You can also add another interesting macro for structuring information to a page — Page Properties. You need to provide a table with two columns inside it, the first being the key and the second being the value of the property. Moreover, the macro can be hidden from the page so that it doesn't interfere with reading the content, but the page will still be marked with the necessary keys.

Note the ID — it is convenient to assign it in order to attach different groups of properties to different pages (or even different groups of properties to one page).

Rapporter

You can generate reports based on tags. For example, the macro Content Report gathers all pages with a specific set of tags.

But a more interesting report is the macro Page Property Report. It also collects all pages with a specific set of tags, but it doesn't just list them; it creates a table (catching the connection to the beginning of the article?), where the columns are keys of the page properties.

This results in a consolidated table of information from various sources. It's nice that it has convenient features: responsive layout, sorting by any column. This report table can also be configured within the macro.

When configuring, you can remove certain columns from the report, set a default state, or specify the number of displayed records. You can also set the page property ID to see only the relevant information.

For example, you have many employee pages, and these pages have a set of properties about the person: their level, location, when they joined the team, and so on. These properties are marked ID = employee_inf. And there is a second set of properties on the same page, which gathers information about the person as part of the team: what role the person performs, which team they belong to, and so on. These properties are marked ID = team_inf. Then, when compiling a report, you can output information for just one ID or both — whichever is more convenient.

The beauty of this approach is that everyone can create the informational table they need, which will not duplicate anything and will update when the main page is updated. For example: a team lead doesn't care when their developers were hired, but it is important what role each of them plays in the team. The team lead will compile a report on the team. An accountant, on the other hand, doesn't care about the roles; they care about positions — they will compile a report on positions. Meanwhile, the source of the information will not be duplicated or transferred.

The final process

Brugsanvisning

So, we can beautifully structure and effectively aggregate information in Confluence using macros as an example. But ideally, the new information should be structured from the start and fit into all the already used aggregation mechanisms.

Here, a combination of macros and templates will help. To encourage people to create new pages in the required format, you can use the macro "Create from Template." It adds a button to the page, and when clicked, a new page is created from the template you need. In this way, you make people work in the format you want from the start.

In the template from which you allow page creation, you need to pre-add tags, the "Page Properties" macro, and a table of the properties you need. I also recommend adding instructions on what values should be entered on the page and the values of the properties.

Then the final process will look like this:

You create a template for a specific type of information.
In this template, you add tags and page properties in the macro.
Opret en roden side hvor som helst med en knap, som når den klikkes, opretter en underliggende side fra skabelonen.
Giv adgang til roden siden for brugere, der potentielt vil generere den nødvendige information (i henhold til den ønskede skabelon ved at klikke på knappen).
Saml en rapport om egenskaberne på siden via de tags, du har angivet i skabelonen.
Du kan glæde dig over, at du har al den nødvendige information i et praktisk format.

Faldgruber

Som kvalitetsingeniør kan jeg sagtens sige, at der ikke findes noget perfekt i verden. Selv guddommelige tabeller er ikke perfekte. Og i den beskrevne proces er der faldgruber.

Hvis du beslutter dig for at ændre navne eller indholdet af sideegenskaberne, skal du opdatere alle de allerede oprettede objekter for at sikre, at deres data korrekt vises i den samlede rapport. Dette er ærgerligt, men på den anden side tvinger det til at tænke grundigt over "arkitekturen" i dit informationssæt, hvilket er en ret interessant opgave.
Du vil være nødt til at skrive en rimelig mængde instruktioner om, hvordan man udfylder informationsskemaer og bruger tags. Men på den anden side kan du også bare sende denne artikel til alle de relevante personer.

Eksempel på opbevaring af ikke-produktdokumentation

Gennem den ovenfor beskrevne proces kan næsten enhver information organiseres. Fordelen ved denne tilgang er, at den er universel: når brugerne vænner sig til den, stopper de med at generere rod. En stor (men ikke gratis) fordel er muligheden for at indsamle forskellige statistikker i realtid og tegne smukke diagrammer baseret på dem.

Jeg vil give et eksempel på vores proces til informationshåndtering om teamet.

For hver person i teamet besluttede vi at oprette et medarbejderkort. Derfor har vi en skabelon, hvor hver ny person kan oprette kortet og holde al sin personlige information der.

Som du kan se, har vi en omfattende tabel over egenskaber og straks en vejledning om, hvordan man præcist skal håndtere denne side. Nogle tags angives af medarbejderne selv efter vejledningen, i skabelonen er der kun de grundlæggende: tag for kortet employee-card, tag for retning direction-involve og tag for teamet team-qa.

Når hver person har oprettet deres eget kort, får vi en fuld tabel med information om medarbejderne. Disse oplysninger kan bruges på forskellige steder. Ressourcechefer kan samle generelle tabeller, mens teamledere kan lave team-tabeller og tilføje team-tags til udvalget.

Ved hjælp af tags kan man se forskellige oversigter, for eksempel om qa-upgrade-plan vil alle opgaver til udvikling af QA blive vist. Hver person fører dog en vigtig historie og sin egen udviklingsplan i deres kort — de skaber en underliggende side fra skabelonen for udviklingsplaner.