Design i Confluence

Hej alla!

Jag heter Masha och jag arbetar som kvalitetssäkringsingenjör inom Tinkoff-gruppen. QA-arbetet innebär många kommunikationer med olika människor från olika team, och jag har dessutom varit projektledare och föreläsare för utbildningsprogram, så mitt kommunikationsnät var så brett som möjligt. Och i ett ögonblick exploderade jag: jag insåg att jag inte längre kunde, inte kunde, inte kunde fylla i ofattbara mängder oläsliga tabeller och dokument.

Jag är säker på att ni alla nu har föreställt er det jag pratar om och svettas kallt: listor med namn utan alfabetisk ordning, tabeller med hundratals kolumner med förskjuten layout, tabeller med tusentals rader där man måste dra sitt finger över musens hjul för att se rubriken, tonvis av sidor med onumrerade instruktioner, hundratals mail som skickas fram och tillbaka med data som måste analyseras och systematiseras för att stoppas in i lika oläsliga tabeller.

Så när jag lugnade ner mig beslöt jag mig för att skriva den här artikeln. Jag kommer att berätta om hur man på ett ordentligt (ibland till och med bekvämt) kan hantera olika typer av icke-produktdokumentation. Jag hoppas att artikeln sprids på nätet och att nivån av elände i angränsande avdelningar till utvecklingen minskar lite grann, och att människor (inklusive jag själv) blir lite lyckligare.

Verktyg

Produktdokumentation lagras ofta nära koden, vilket är bra. Men icke-produktdokumentation lagras ofta lite här och där. Ofta försöker folk föra över information från olika ställen till Confluence, och vi gör inget undantag. Så allt som följer handlar om det.

Confluence är i grunden en avancerad wiki-motor. Den möjliggör arbete med data i olika visningsformer: text med formatering, tabeller, olika diagram. Det är ett mycket intressant och kraftfullt verktyg, men om man inte vet hur man förbereder det, får man bara en ny avstjälpningsplats för oläsliga dokument. Jag ska lära er att förbereda det!

Makron

Nästan all magi i Confluence bygger på makron. Det finns många makron och de kan kombineras med varandra. De är både betal- och gratisversioner, nedan kommer olika exempel på makron med länkar till dokumentation för dem.

Gränssnittet för att arbeta med makron är mycket enkelt. För att lägga till ett makro, tryck på pluset och välj det element du behöver från listan.

Om makrot är självförsörjande, det vill säga inte kräver att något annat sätts in i sig självt, ser det ut som en block.

Om makret behöver något för att fungera, ser det ut som en ram.

Inom samma ram kan man placera så många andra som helst, så länge det finns logik i din pyramide.

Varje makro har en förhandsvisning: här kan man direkt se om du har fyllt i och ställt in makrot korrekt.

Mallar

Utöver makron finns det ett praktiskt verktyg för förhandsifyllning av innehåll – det är en mall.
Mallar kan användas när du skapar vilken sida som helst: tryck bara på de tre punkterna bredvid knappen "Skapa" och välj den mall du behöver.

Då läggs allt innehåll från mallen till i den skapade sidan.

Att skapa sidor från mallar kan vem som helst göra, men att skapa eller redigera själva mallarna får endast de som har rätt till det. En mall kan även kompletteras med ytterligare instruktioner om hur sidan bör underhållas.

Magin i tabeller

Egentligen tycker jag, som tekniker, mycket om tabeller och kan nästan alltid vända information i dem (även om det inte alltid är effektivt). Själva tabellerna är tydliga, strukturerade, skalbara, magiska!

Men även en så fantastisk entitet som en tabell kan förstöras. Det går också att använda dem på ett lyckat sätt och till och med förbättra dem. Mer om detta nedan.

Filtrering (betald plugin)

Vilken stor, oläslig tabell som helst kan göras lite mindre stor och lite mer läsbar med hjälp av filtrering. För detta kan du använda ett betalt makro. «Tabellfilter».

Inuti detta makro måste en tabell sättas in (även den fulaste, det viktigaste är att få in den helt). I makrot kan du välja kolumner för filtrering med en rullgardinsmeny, textfilter, numeriska filter och datumfilter.

Tänk dig att all information om kandidater för alla lediga tjänster skrivs in i en tabell. Naturligtvis osorterad – folk kommer ju inte till intervju i alfabetisk ordning. Och du måste förstå om du har intervjuat en specifik kandidat tidigare. Du måste bara stoppa denna mardröm i filtreringsmakrot, lägga till ett textfilter på efternamn – och voila, informationen är på skärmen.

Det är värt att notera att filtrering av stora tabeller kan påverka systemets prestanda och sidladdningstid, så att placera en stor tabell i ett filter är en tillfällig lösning, det är bättre att bygga en process där folk inte behöver skapa stora, oläsliga tabeller (ett exempel på processen kommer i slutet av artikeln).

Sortering (betald plugin)

Med hjälp av den magiska makron «Tabellfilter» kan man också ange standard sortering för valfri kolumn och numrera rader. Eller så kan man klicka på vilken kolumn i tabellen som helst som har placerats i filtermakrot, och sortering kommer att ske efter den kolumnen.

Till exempel, om du har samma tabell med kandidater och behöver uppskatta hur många intervjuer som genomfördes under en viss månad, - sortera efter datum och njut.

Pivottabeller (betald plugin)

Nu går vi till ett intressantare fall. Tänk dig att din tabell är jättestor och du behöver räkna något på den. Naturligtvis kan du kopiera den till Excel, räkna vad du behöver och ladda upp data tillbaka till Confluence. Men du kan också en gång tillämpa makrot «Pivottabell» och få samma resultat, bara att det också uppdateras.

Till exempel: om du har en tabell som samlar data om alla anställda - var de geografiskt befinner sig och vilken position de har. För att räkna hur många personer som finns i varje stad, behöver du välja i makrot «Pivottabell» den rad efter vilken data aggregeras (plats) och typ av operation (addition).

Självklart kan du gruppera efter flera kriterier samtidigt, alla möjligheter kan du se i dokumentationen.

Diagram (betald plugin)

Som jag redan nämnt, älskar inte alla tabeller lika mycket som jag gör. Tyvärr gillar de flesta chefer dem överhuvudtaget inte. Men alla älskar verkligen färgglada diagram.
Skapararna av Confluence visste säkert detta (de har säkert också en chef som älskar rapporter och diagram, hur skulle det annars vara). Så du kan använda den magiska makron «Diagram från tabell». I denna makro behöver du placera pivottabellen från föregående punkt, och vips - dina grå tråkiga data är vackert visualiserade.

Självklart finns det också inställningar i denna makro. Länken till dokumentationen för vilket makro som helst kan du hitta i redigeringsläget för denna makro.

Enkelhet i aggregering

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

Taggar

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

You can add any number of tags to any page. If you click on a tag, you'll 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.

Sidproperty

You can also add another interesting macro for structuring information to the page — «Sidproperty». Inside, you need to provide a table with two columns; the first will serve as the key, and the second as the value of the property. Additionally, the macro can be hidden from the page so that it does not interfere with reading the content, but the page will still be marked with the necessary keys.

Note the ID — it's convenient to set it to apply different groups of properties to different pages (or even different groups of properties on one page).

Rapporter

You can collect reports by tags. For example, the macro «Innehållsrapport» collects all pages with a specific set of tags.

But a more interesting report is the macro «Sidpropertyrapport». It also collects all pages with a specific set of tags, but instead of simply listing them, it creates a table (catch the connection to the beginning of the article?), where the columns are the keys of the page properties.

It results in a summary table of information from various sources. It's nice that it has useful functions: 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 the default state, or the number of displayed records. You can also specify the ID of the page property to see only the information you need.

Till exempel, du har många anställdasidor, och dessa sidor har en uppsättning egenskaper om personen: vilken nivå de har, var de befinner sig, när de kom till teamet och så vidare. Dessa egenskaper är markerade ID = employee_inf. Det finns också en andra uppsättning egenskaper på samma sida, där informationen om personen som en del av teamet är samlad: vilken roll personen har, i vilket team de befinner sig och så vidare. Dessa egenskaper är markerade ID = team_inf. Så när du sammanställer en rapport kan du antingen visa information baserat på ett ID eller på två — beroende på vad som är bekvämare.

Skönheten med denna metod är att varje person kan samla den informationstabell de behöver, som inte duplicerar något och som uppdateras när huvud sidan uppdateras. Till exempel: en teamledare bryr sig inte om när hans utvecklare började arbeta, utan om vilken roll var och en av dem har i teamet. Teamledaren kommer att samla sin rapport om teamet. En revisor bryr sig överhuvudtaget inte om vilken roll som utförs, men det är viktigt med positionerna - han kommer att samla sin rapport om positionerna. Samtidigt kommer informationskällan inte att dupliceras eller flyttas.

Slutprocessen

Instruktion

Så, vi kan vackert strukturera och effektivt aggregera information i Confluence genom att använda makron. Men i idealfallet bör vi se till att ny information omedelbart är strukturerad och kommer in i alla redan använda aggregationsmekanismer.

Här kommer en kombination av makron och mallar till hjälp. För att få människor att skapa nya sidor i rätt format kan du använda makrot "Skapa från mall". Det lägger till en knapp på sidan, som när man klickar på den skapar en ny sida från den mall du önskar. Så du tvingar människor att omedelbart arbeta i det format du behöver.

I mallen, från vilken du ger möjlighet att skapa en sida, behöver du på förhand lägga till etiketter, makrot "Egenskaper för sidan" och tabellen med de egenskaper du behöver. Jag rekommenderar också att lägga till instruktioner om vilka värden som ska fyllas på sidan och värdena för egenskaperna.

Då kommer slutprocessen att se ut så här:

1. Du skapar en mall för information av viss typ.
2. I denna mall lägger du till etiketter och sidans egenskaper i makrot.
3. På valfri plats skapar du en huvudsida med en knapp, som, när du klickar på den, skapar en undersida utifrån en mall.
4. Du bjuder in användare till huvudsidan som potentiellt kan generera den information som behövs (enligt mallen, genom att klicka på knappen).
5. Du samlar en rapport om sidans egenskaper via de etiketter som du angav i mallen.
6. Du är glad: du har all nödvändig information i ett bekvämt format.

Fällor

Som kvalitetsingenjör kan jag utan tvekan påstå att inget är perfekt i världen. Även gudomliga tabeller är inte perfekta. Och i processen som beskrivits ovan finns det fällor.

• Om du beslutar dig för att ändra namnen eller sammansättningen av sidans egenskaper, måste du uppdatera alla redan skapade objekt så att deras data korrekt dras in i den sammanställda rapporten. Detta är tråkigt, men å andra sidan tvingar det dig att noggrant tänka igenom "arkitekturen" av din informationsuppsättning, vilket är en mycket intressant uppgift.
• Du måste skriva ett betydande antal instruktioner om hur man fyller i informationstabeller och använder etiketter. Men å andra sidan kan du helt enkelt skicka den här artikeln till alla berörda.

Exempel på lagring av icke-produktdokumentation

Genom den process som beskrivits ovan kan du organisera lagring av nästan all information. Det som är fantastiskt med metoden är att den är universell: när användare vänjer sig vid den slutar de att generera kaos. En stor (men inte gratis) fördel är möjligheten att samla in olika statistiker i realtid och skapa vackra diagram baserat på dem.

Jag kommer att ge ett exempel på vår informationshantering om teamet.

För varje person i teamet bestämde vi oss för att skapa ett medarbetarkort. Därför har vi en mall, enligt vilken varje ny person skapar sitt kort och håller reda på all personlig information där.

Som ni ser har vi en omfattande tabell med egenskaper och redan finns det instruktioner om hur man leder denna sida. En del etiketter fylls i av medarbetarna enligt instruktionerna, i mallen finns bara de grundläggande: etikett för kortet employee-card, etikett för riktning direction-involve och etikett för teamet team-qa.

I slutändan, efter att varje person har skapat sitt kort, får vi en fullständig tabell med information om anställda. Denna information kan användas på olika ställen. Resurschefer kan sammanställa gemensamma tabeller, och teamledare kan skapa teamtabeller genom att lägga till lagets tagg i urvalet.

Genom taggar kan man se olika sammanställningar, till exempel om qa-upgrade-plan kommer alla uppgifter om QA-utveckling att visas. Varje person i sitt anställdkort håller en viktig historik och sin utvecklingsplan - skapar en inbäddad sida från mallen för utvecklingsplaner.

Slutsats

Dokumentera allt på ett sätt så att det inte är pinsamt och så att användarna inte ska behöva lida!

Jag hoppas verkligen att artikeln kommer att vara användbar och att det kommer att bli ordning i alla dokumentationer i världen.

Källa: habr.com