Hei!
Jeg heter Masha, jeg jobber som kvalitetssikringsingeniør i Tinkoff-gruppen. QA-arbeid innebærer mye kommunikasjon med ulike personer fra ulike team, og jeg var også leder og foreleser for utdanningsprogrammer, så kommunikasjonskartet mitt ble så bredt som mulig. Og på et tidspunkt eksploderte jeg: Jeg innså at jeg ikke kan, jeg kan ikke, jeg kan ikke fylle ut haugevis av uleselige tabeller og dokumenter.
Hver og en av dere har sikkert forestilt dere hva jeg snakker om og brøt ut i kaldsvette: lister over etternavn uten alfabetisk rekkefølge, tabeller med hundrevis av kolonner med skjev layout, tabeller med tusenvis av linjer der du trenger å tørke fingeren. på musehjulet for å se header, tonnevis av sider med unummererte instruksjoner, hundrevis av brev sendt til hverandre med data som må analyseres og systematiseres og stappes inn i like uleselige tabeller.
Og så, da jeg kjølte meg ned litt, bestemte jeg meg for å skrive denne artikkelen. Jeg vil snakke om hvordan du normalt (selv noen ganger praktisk) kan vedlikeholde en rekke ikke-produktdokumentasjon. Jeg håper at artikkelen vil spre seg over Internett og helvetesnivået i avdelingene ved siden av utviklingen vil i det minste minke litt, og folk (inkludert meg selv) vil bli litt gladere.
Verktøy
Produktdokumentasjon holdes ofte ved siden av koden, noe som er bra. Og ikke-produktdokumentasjon lagres vanligvis hvor som helst. Folk prøver ofte å flytte informasjon fra forskjellige steder til Confluence, og vi er intet unntak. Så resten av historien handler om ham.
Generelt er Confluence en avansert wiki-motor. Den lar deg jobbe med data i forskjellige typer visning: tekst med formatering, tabeller, ulike diagrammer. Dette er et veldig interessant og kraftig verktøy, men hvis du ikke vet hvordan du forbereder det, vil du ende opp med nok en dump av uleselige dokumenter. Jeg skal lære deg å lage mat!
Makroer
Nesten all magien til Confluence kommer fra makroer. Det er mange makroer, og de kan kombineres med hverandre. De kan være betalt eller gratis; nedenfor vil det være ulike eksempler på makroer med lenker til dokumentasjon for dem.
Grensesnittet for å jobbe med makroer er så enkelt som mulig. For å legge til en makro, må du klikke på plusset og velge ønsket element fra listen.
Hvis en makro er selvstendig, det vil si at den ikke krever å sette inn noe annet i seg selv, ser den ut som en blokk.
Hvis en makro krever at noe er plassert inne i den for at den skal fungere, ser den ut som en ramme.
Samtidig kan du plassere så mange andre du vil innenfor én ramme, så lenge det er logikk i pyramiden din.
Hver makro har en forhåndsvisning: den viser umiddelbart om du fylte ut og konfigurerte makroen riktig.
maler
I tillegg til makroer er det et praktisk verktøy for forhåndsutfylling av innhold - en mal.
Maler kan brukes når du lager hvilken som helst side: bare klikk på de tre prikkene ved siden av "Opprett"-knappen og velg ønsket mal.
Da vil alt innholdet som er i malen bli lagt til den opprettede siden.
Alle kan lage sider fra maler, men bare de som har rettigheter til å lage eller redigere malene selv kan gjøre det. Du kan legge til flere instruksjoner i malen om hvordan siden skal vedlikeholdes.
Bordenes magi
Som tekniker elsker jeg faktisk tabeller og kan pakke inn nesten all informasjon i dem (selv om dette ikke alltid er effektivt). Selve tabellene er klare, strukturerte, skalerbare, magiske!
Men selv en så fantastisk enhet som et bord kan bli ødelagt. Og du kan med hell bruke den og til og med forbedre den. Mer om dette nedenfor.
Filtrering (betalt plugin)
Enhver stor, uleselig tabell kan gjøres litt mindre stor og litt mer lesbar ved å bruke filtrering. Du kan bruke en betalt makro for dette .
Du må sette en tabell inne i denne makroen (selv den styggeste er mulig, det viktigste er å presse den i sin helhet). I makroen kan du velge kolonner for rullegardinfilteret, tekstfilteret, numerisk filter og datofilter.
Tenk deg at all informasjon om kandidater for alle ledige stillinger er registrert i en tabellliste. Naturligvis, usortert - folk kommer til intervjuer ikke i alfabetisk rekkefølge. Og du må forstå om du har intervjuet en spesifikk søker før. Du trenger bare å sette dette helvete inn i en filtermakro, legge til et tekstfilter etter etternavn - og vips, informasjonen er på skjermen din.
Det er verdt å merke seg at filtrering av store tabeller kan påvirke systemytelse og sideinnlastingstider, så å sette en stor tabell i et filter er en midlertidig krykke; det er bedre å bygge en prosess der folk ikke trenger å lage store, uleselige tabeller (en eksempel på prosessen vil være på slutten av artikkelen).
Sortering (betalt plugin)
Bruke en magisk makro Du kan også angi standardsortering på hvilken som helst kolonne og nummerere radene. Eller klikk på en hvilken som helst kolonne i tabellen som er satt inn i filtermakroen, og sortering vil skje etter den kolonnen.
For eksempel har du samme tabell med søkere og du må anslå hvor mange intervjuer som ble gjennomført i en bestemt måned – sorter etter dato og vær fornøyd.
Pivottabeller (betalt plugin)
La oss nå gå videre til en mer interessant sak. Tenk deg at bordet ditt er stort og du må beregne noe ut fra det. Du kan selvfølgelig kopiere det inn i Excel, beregne hva du trenger og laste opp dataene tilbake til Confluence. Kan du bruke makroen en gang? og få samme resultat, bare oppdatert.
For eksempel: du har en tabell som samler inn data fra alle ansatte – hvor de befinner seg geografisk og hvilke stillinger de har. For å beregne hvor mange mennesker det er i hver by, må du velge raden i pivottabellmakroen som samler dataene (sted) og operasjonstype (tillegg).
Naturligvis kan du gruppere etter flere kriterier samtidig, alle muligheter kan sees .
Diagrammer (betalt plugin)
Som jeg sa, ikke alle elsker bord like mye som meg. Dessverre liker de fleste ledere dem ikke i det hele tatt. Men alle elsker virkelig fargerike diagrammer.
Skaperne av Confluence visste absolutt om dette (de har sikkert også sjefer som elsker rapporter og diagrammer, hvor ville de vært uten det). Derfor kan du bruke den magiske makroen . I denne makroen må du sette pivottabellen fra forrige avsnitt, og voila - dine grå kjedelige data er vakkert visualisert.
Naturligvis har denne makroen også innstillinger. En lenke til dokumentasjonen for en hvilken som helst makro kan bli funnet i redigeringsmodusen til den makroen.
Enkel aggregering
Informasjonen fra de foregående avsnittene var sannsynligvis ikke en åpenbaring for deg. Men nå vet du definitivt hvordan du bruker makroer, og jeg kan gå videre til den mer interessante delen av artikkelen.
Tags
Det er ille når folk lagrer informasjon i én ustrukturert artikkel eller en stor tabell. Det er enda verre når deler av denne informasjonen ikke bare er uleselig formatert, men også spredt over hele Confluence. Heldigvis er det mulig å samle spredt informasjon på ett sted. For å gjøre dette må du bruke (merker kjent for alle fra sosiale nettverk).
Du kan legge til et hvilket som helst antall tagger på hvilken som helst side. Ved å klikke på en tag kommer du til en aggregeringsside med lenker til alt innhold med den taggen, samt et sett med relaterte tagger. Relaterte tagger er de som vises ofte på samme side.
Sideegenskaper
Du kan legge til en annen interessant makro på siden for å strukturere informasjon - . Inne i den må du sende inn en tabell med to kolonner, den første vil være nøkkelen, og den andre vil være verdien av eiendommen. Dessuten kan makroen skjules fra siden slik at den ikke forstyrrer lesingen av innholdet, men siden vil fortsatt være merket med de nødvendige tastene.
Vær oppmerksom på ID-en - det er praktisk å sette den til å tilordne forskjellige grupper av eiendommer til forskjellige sider (eller til og med forskjellige grupper av eiendommer til en side).
Reports
Du kan samle inn rapporter ved å bruke tagger. For eksempel makro samler alle sider med et spesifikt sett med tagger.
Men en mer interessant rapport er makroen . Den samler også alle sider med et bestemt sett med tagger, men den viser ikke bare en liste over dem, men lager en tabell (fanger du sammenhengen med begynnelsen av artikkelen?), der kolonnene er siden eiendomsnøkler.
Resultatet er en sammendragstabell med informasjon fra forskjellige kilder. Det er fint at den har praktiske funksjoner: adaptiv layout, sortering etter hvilken som helst kolonne. En slik rapporteringstabell kan også konfigureres i en makro.
Når du konfigurerer, kan du fjerne noen kolonner fra rapporten, angi en standardtilstand eller antall poster som vises. Du kan også angi at sideegenskaps-IDen bare skal se informasjonen du trenger.
For eksempel har du mange medarbeidersider, disse sidene har et sett med egenskaper om personen: hvilket nivå han er, hvor han er, når han ble med i teamet, og så videre. Disse egenskapene er merket ID = ansatt_info. Og det er et andre sett med egenskaper på samme side, som inneholder informasjon om personen som en del av teamet: hvilken rolle personen spiller, hvilket lag han er på, og så videre. Disse egenskapene er merket ID = team_inf. Deretter, når du kompilerer en rapport, kan du kun vise informasjon for én ID eller to samtidig - avhengig av hva som passer best.
Det fine med denne tilnærmingen er at alle kan sette sammen informasjonstabellen de trenger, som ikke vil duplisere noe og vil bli oppdatert når hovedsiden oppdateres. For eksempel: det spiller ingen rolle for en teamleder når utviklerne hans fikk jobb, men det er viktig hvilken rolle hver av dem spiller i teamet. Laglederen vil samle en rapport om laget. Og regnskapsføreren bryr seg generelt ikke om hvem som utfører hvilken rolle, men stillingene er viktige - han vil lage en rapport om stillingene. I dette tilfellet vil ikke informasjonskilden dupliseres eller overføres.
Endelig prosess
Instruksjon
Så vi kan strukturere og effektivt samle informasjon i Confluence ved å bruke makroer som eksempel. Men ideelt sett må du sørge for at ny informasjon umiddelbart blir strukturert og faller inn i alle aggregeringsmekanismene som allerede er i bruk.
Det er her en haug med makroer og maler vil komme til unnsetning. For å tvinge folk til å opprette nye sider i ønsket format, kan du bruke Makroen Opprett fra mal. Den legger til en knapp på siden, når den klikkes, opprettes en ny side fra malen du trenger. På denne måten tvinger du folk til umiddelbart å jobbe i det formatet du trenger.
I malen du oppretter en side fra, må du legge til etiketter, en "Sideegenskaper"-makro og en tabell over egenskapene du trenger på forhånd. Jeg anbefaler også å legge til instruksjoner om hvilke verdier som skal fylles ut på siden, og eiendomsverdier.
Da vil den endelige prosessen se slik ut:
- Du lager en mal for en bestemt type informasjon.
- I denne malen legger du til etiketter og sideegenskaper i en makro.
- På et hvilket som helst passende sted, lag en rotside med en knapp, klikk på som oppretter en underside fra malen.
- Du lar brukere gå til rotsiden, som potensielt vil generere den nødvendige informasjonen (i henhold til den nødvendige malen, ved å klikke på en knapp).
- Du samler inn en rapport om sideegenskapene ved å bruke kodene du spesifiserte i malen.
- Gled deg: du har all nødvendig informasjon i et praktisk format.
Fallgruver
Som kvalitetsingeniør kan jeg trygt si at ingenting er perfekt i verden. Selv guddommelige bord er ufullkomne. Og det er fallgruver i prosessen ovenfor.
- Hvis du bestemmer deg for å endre navn eller sammensetning av sideegenskaper, må du oppdatere alle allerede opprettede objekter slik at deres data er korrekt inkludert i sammendragsrapporten. Dette er trist, men på den annen side tvinger det deg til å tenke i detalj på "arkitekturen" til informasjonssettet ditt, noe som er en veldig interessant oppgave.
- Du må skrive en god del instruksjoner om hvordan du fyller ut informasjonstabeller og bruker tagger. Men på den annen side kan du bare treffe alle de riktige personene med denne artikkelen.
Eksempel på lagring av ikke-produktdokumentasjon
Gjennom prosessen beskrevet ovenfor kan du organisere lagringen av nesten all informasjon. Det fine med tilnærmingen er at den er universell: Når brukerne blir vant til den, slutter de å skape et rot. Et annet stort (men ikke gratis) pluss er muligheten til å samle ulike statistikker i farten og tegne vakre diagrammer basert på dem.
La meg gi deg et eksempel på prosessen vår for å vedlikeholde informasjon om et team.
Vi bestemte oss for å lage et ansattkort for hver person i teamet. Følgelig har vi en mal som hver ny person oppretter dette kortet for seg selv og opprettholder all personlig informasjon i det.
Som du kan se, har vi en detaljert tabell over eiendommer og har umiddelbart instruksjoner om nøyaktig hvordan du vedlikeholder denne siden. Noen av kodene legges til av de ansatte selv etter instrukser, malen inneholder kun de viktigste: kortbrikke ansatt-kort, retningsskilt retning-involvere og team tag lag-qa.
Som et resultat, etter at alle har laget et kort for seg selv, oppnås en komplett tabell med informasjon om ansatte. Denne informasjonen kan brukes på forskjellige punkter. Ressursforvaltere kan samle generelle tabeller for seg selv, og teamledere kan opprette teamtabeller ved å legge til en teamtag i utvalget.
Du kan se forskjellige sammendrag etter tagger, for eksempel qa-oppgraderingsplan Alle QA-utviklingsoppgaver vil bli vist. Samtidig beholder hver person en viktig historie og sin egen utviklingsplan i medarbeiderkortet sitt - lager en nestet side fra malen for utviklingsplaner.
Konklusjon
Oppretthold all dokumentasjon på en slik måte at det ikke er skam i det, og det ikke forårsaker uutholdelig smerte for brukerne!
Jeg håper virkelig at artikkelen vil være nyttig og orden vil komme til all dokumentasjon i verden.
Kilde: www.habr.com