🥇Design i Confluence

Hei alle sammen!

Eg heiter Masha, og eg arbeider som kvalitetssikrar i Tinkoff-gruppa. Jobben som QA inneber mange kommunikasjonar med ulike folk frå forskjellige team, og sidan eg også har vore leiar og undervisar i utdanningsprogram, har eg eit breitt kommunikasjonskart. Og i eit augneblink fekk eg eit utbrudd: eg innsåg at eg ikkje lenger kunne fylle ut vonde tonn med uleste tabellar og dokument.

Sannsynlegvis har kvart og ein av dykk no forestilt seg det eg snakkar om, og fått svette på panna: lister med namn utan alfabetisk rekkefølgje, tabellar med hundrevis av kolonnar der oppsettet er øydelagt, tabellar med tusenvis av rader der ein må gni fingeren mot musa for å sjå overskrifta, tonn med ikkje-nummererte instruksjonssider, hundrevis av e-postar som blir sendt fram og tilbake med data som må analyserast og systematiserast og puttast inn i like uleste tabellar.

Og når eg kjølte meg litt ned, bestemte eg meg for å skrive denne artikkelen. Eg vil fortelje om korleis ein kan føre diverse ikkje-produktdokumentasjon på ein ordentleg (og til og med ofte behageleg) måte. Eg håpar at artikkelen vil spreie seg i nettet og at nivået av elendighet i nabodepartementa til utviklinga vil bli litt mindre, og at folk (inkludert meg sjølv) vil bli eit lite grann meir lukkelege.

Tools

Produktdokumentasjonen blir oftast lagra nær koden, og det er bra. Ikkje-produktdokumentasjonen blir derimot ofte lagra overalt. Folk prøver ofte å flytte informasjon frå ulike stader til Confluence, og vi er ikkje unntaket. Så heile vidare fortelinga handlar om det.

Confluence er eigentleg ein avansert wiki-motor. Det gir deg moglegheit til å arbeide med data på ulike vis: tekst med formatering, tabellar, diverse diagram. Det er eit svært interessant og kraftig verktøy, men dersom ein ikkje veit korleis ein skal bruke det, får ein berre ei ny søppelhaug med uleste dokument. Eg vil lære deg å bruke det!

Makros

Nesten all magia i Confluence er basert på makros. Det finst mange makros, og dei kan kombinerast med kvarandre. Nokre er betalte, og andre er gratis; det vil kome diverse døme på makros med lenker til dokumentasjonen for dei.

Grensesnittet for å arbeide med makros er svært enkelt. For å legge til eit makro, trykker ein på pluss-teiknet og vel den aktuelle boka frå lista.

Hvis makroen er selvforsynt, det vil si at den ikke krever at noe annet settes inn i seg, ser den ut som en blokk.

Hvis makroen trenger at noe settes inni den for å fungere, ser den ut som en ramme.

Man kan imidlertid plassere så mange andre inn i en ramme, så lenge det er logikk i pyramiden din.

Hver makro har en forhåndsvisning: der kan man umiddelbart se om man har fylt ut og konfigurert makroen riktig.

Malverk

I tillegg til makroer finnes det et praktisk verktøy for forhåndsutfylling av innhold – det er malen.
Malene kan brukes når man oppretter hvilken som helst side: bare klikk på de tre prikkene ved siden av knappen "Opprett" og velg ønsket mal.

Da vil alt innholdet i malen legges til den opprettede siden.

Alle kan opprette sider fra maler, men bare de som har tillatelse kan opprette eller redigere selve malene. Man kan legge til ekstra instruksjoner til malen om hvordan siden bør føres.

Tabellenes magi

Som teknisk person elsker jeg faktisk tabeller og kan nesten pakke hvilken som helst informasjon inn i dem (selv om det ikke alltid er effektivt). Selve tabellene er klare, strukturerte, skalerbare, magiske!

Men selv en så fantastisk enhet som tabellen kan ødelegges. Den kan også brukes smart og til og med forbedres. Mer om dette nedenfor.

Filtrering (betalt plugin)

Enhver stor, uleselig tabell kan gjøres litt mindre stor og litt mer lesbar ved hjelp av filtrering. For dette kan man bruke en betalt makro. «Tabellfilter».

Inn i denne makroen må man putte tabellen (man kan til og med bruke den styggeste, det viktigste er å få den helt inn). I makroen kan man velge kolonner for filtrering fra en rullegardinliste, tekstfilter, numerisk filter og datofilter.

Tenk deg at all informasjon om kandidater til alle stillinger blir registrert i en tabell. Naturligvis usortert – folk kommer ikke til intervjuene i alfabetisk rekkefølge. Og du må finne ut om du har intervjuet en bestemt søker tidligere. Bare putt dette kaoset inn i filtermakroen, legg til tekstfilter etter etternavn – og voilá, informasjonen er på skjermen.

Det er verdt å merke seg at filtrering av store tabeller kan påvirke systemets ytelse og lastetid for sider, så det å plassere en stor tabell i filteret er en midlertidig løsning. Det er bedre å bygge en prosess der folk ikke må lage store, uleselige tabeller (et eksempel på prosessen vil komme på slutten av artikkelen).

Sortering (betalt plugin)

Med den magiske makroen «Tabellfilter» kan du også angi standard sortering etter hvilken som helst kolonne og nummerere radene. Eller klikk på hvilken som helst kolonne i tabellen som er plassert i filtermakroen, så vil sortering skje etter den kolonnen.

For eksempel, hvis du har den samme tabellen med søkere og må finne ut hvor mange intervjuer som har blitt holdt i en viss måned, sorter etter dato og nyt.

Pivot-tabeller (betalt plugin)

La oss nå gå videre til en mer interessant sak. Tenk deg at tabellen din er gigantisk, og du må gjøre noen beregninger på den. Selvfølgelig kan du kopiere den til Excel, gjøre de nødvendige beregningene og laste dataene tilbake til Confluence. Eller du kan bruke makroen «Pivot-Tabell» én gang for å få det samme resultatet, bare at det oppdateres.

For eksempel: dersom du har en tabell som samler data om alle ansatte — hvor de befinner seg geografisk og hvilke stillinger de har. For å finne ut hvor mange personer det er i hver by, må du velge i makroen «Pivot-Tabell» den raden som dataene aggregeres etter (plassering) og type operasjon (summering).

Selvfølgelig kan du gruppere etter flere kriterier samtidig, alle muligheter kan du se i dokumentasjonen.

Diagrammer (betalt plugin)

Som jeg allerede har nevnt, er ikke alle like glade i tabeller som jeg er. Dessverre liker de fleste ledere dem overhodet ikke. Men alle elsker fargerike diagrammer.
Skaperne av Confluence visste sikkert dette (de har nok også overordnede som liker rapporter og diagrammer, hva ville de gjort uten dem). Derfor kan du benytte deg av den magiske makroen «Diagram fra tabell». I denne makroen må du legge inn pivot-tabellen fra forrige punkt, og vips — de grå, kjedelige dataene dine er pent visualisert.

Selvfølgelig finnes det innstillinger også i denne makroen. En lenke til dokumentasjonen for hvilken som helst makro kan du finne i redigeringsmodus for den makroen.

Enkelhet i aggregering

Informasjonen fra de forrige punktene har sikkert ikke vært åpenbar for deg. Men nå kan du definitivt bruke makroer, og jeg kan gå videre til den mer interessante delen av artikkelen.

Merker

Det er dårlig når folk lagrer informasjon i en enkelt, ustrukturert artikkel eller en enorm tabell. Enda verre er det når deler av denne informasjonen ikke bare er uleselig formatert, men også spredt utover Confluence. Heldigvis er det mulig å samle den spredte informasjonen på ett sted. For dette må du bruke etiketter (de samme som alle kjenner fra sosiale medier).

Du kan legge til et valgfritt antall etiketter på hvilken som helst side. Hvis du klikker på en etikett, kommer du til en aggregasjonsside hvor det finnes lenker til alt innhold med denne etiketten, samt et sett med relaterte etiketter. Relaterte etiketter er de som ofte forekommer på samme side.

Sideegenskaper

Du kan legge til en annen interessant makro for å strukturere informasjon — «Sideegenskaper». I den må du sende inn en tabell med to kolonner, hvor den første vil være nøkkelen og den andre verdien av egenskapen. Dessuten kan makroen skjules fra siden, slik at den ikke forstyrrer lesingen av innholdet, men siden vil fortsatt bli merket med de nødvendige nøklene.

Merk ID-en — det er praktisk å tilordne ulike grupper av egenskaper til ulike sider (eller til og med ulike grupper av egenskaper til én side).

Rapporter

Rapporter kan samles basert på etiketter. For eksempel samler makroen «Innholdsrapport» alle sidene med et bestemt sett av etiketter.

Men en mer interessant rapport er makroen «Sideegenskapsrapport». Den samler også alle sidene med et bestemt sett av etiketter, men ikke bare viser dem i en liste, men lager en tabell (ser du forbindelsen til starten av artikkelen?), hvor kolonnene er nøkkene av sidens egenskaper.

Det resulterer i en oppsummeringstabell over informasjon fra ulike kilder. Det er hyggelig at den har praktiske funksjoner: responsiv design, sortering etter hvilken som helst kolonne. Denne rapporttabellen kan også konfigureres inne i makroen.

Ved konfigurasjon kan du fjerne visse kolonner fra rapporten, sette standardstatus eller antall viste poster. Og du kan også angi ID-en til sidens egenskap for å se kun informasjonen du trenger.

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. There is also a second set of properties on the same page, which collects information about the person as part of the team: what role the person performs, what team they are in, and so on. These properties are marked ID = team_inf. Then, when generating a report, you can pull information based on a single ID or both at once — whichever is more convenient.

The beauty of this approach is that anyone can compile the information table they need, which will not have any duplicates and will be updated whenever the main page is updated. For example, the team lead doesn’t care when their developers started working, but it’s important what role each one plays in the team. The team lead will compile a report on the team. Meanwhile, the accountant doesn’t care what roles are performed, but it’s important to know the positions — they will compile a report on positions. The source of information will not be duplicated or transferred.

Final process

Bruksanvisning

So, we can beautifully structure and efficiently aggregate information in Confluence using macros as an example. Ideally, we need to ensure that new information is immediately structured and into all existing aggregation mechanisms.

Here, the 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, which, when clicked, creates a new page from the template you want. In this way, you make people work in the format you need right away.

In the template from which you allow page creation, you need to pre-add tags, the "Page Properties" macro, and a table of the necessary properties. I also recommend adding instructions on what values should fill 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.
Du kan opprette en rot side med en knapp hvor du klikker for å lage en underside fra en mal, hvor som helst.
Du lar brukerne, som potensielt vil generere nødvendig informasjon (i den nødvendige malen ved å klikke på knappen), gå inn på rot siden.
Du samler rapporten om egenskapene til siden gjennom etikettene du har angitt i malen.
Du glede deg: du har all nødvendig informasjon i et praktisk format.

Feller

Som kvalitetsingeniør kan jeg trygt si at ingenting er perfekt i verden. Selv guddommelige tabeller er ikke uten feil. Og det er feller i den prosessen som er nevnt ovenfor.

Hvis du bestemmer deg for å endre navn eller sammensetning av egenskapene til siden, må du oppdatere alle allerede opprettede objekter for at dataene deres skal hentes korrekt til den samlede rapporten. Dette er trist, men på den annen side tvinger det deg til å tenke grundig gjennom "arkitekturen" til informasjonssettet ditt, noe som er en ganske interessant oppgave.
Du må skrive et betydelig antall instruksjoner om hvordan du fyller ut informasjons tabeller og bruker etiketter. Men på den annen side kan du bare sende denne artikkelen til alle nødvendige mennesker.

Eksempel på lagring av ikke-produktdokumentasjon

Gjennom prosessen beskrevet ovenfor kan du organisere lagring av nesten hvilken som helst informasjon. Fordelen med tilnærmingen er at den er universell: når brukerne venner seg til den, slutter de å generere rot. En stor (men ikke gratis) fordel er muligheten til å samle inn variert statistikk i sanntid og lage vakre diagrammer.

Jeg vil gi et eksempel på vår prosess for informasjonsbehandling om teamet.

For hver person i teamet bestemte vi oss for å lage et ansattkort. Derfor har vi en mal hvor hver ny person lager dette kortet og fører all personlig informasjon i det.

Som du ser, har vi en omfattende tabell med egenskaper, og det finnes umiddelbart instruksjoner om hvordan man fører denne siden. Noen etiketter settes av ansatte etter instruksjonene; i malen er det bare de viktigste: etikett for kortet employee-card, etikett for retning direction-involve og etikett for teamet team-qa.

Når alle har opprettet sine kort, får man en komplett tabell med informasjon om ansatte. Denne informasjonen kan brukes på ulike steder. Ressursledere kan samle seg felles tabeller, mens teamlederne kan opprette teamtabeller ved å legge til teamtaggen i utvalget.

Gjennom tagger kan man se ulike oppsummeringer, for eksempel for qa-upgrade-plan vil alle oppgaver relatert til utvikling av QA bli vist. Hver person fører en viktig historie og sin utviklingsplan i sitt ansattkort – de lager en underliggende side fra malen for utviklingsplaner.