Confluence är ett väldigt flexibelt verktyg för att strukturera din systemdokumentation, det går snabbt och enkelt att skapa nya sidor och organisera informationen i olika “Space”. Men det kan bli ganska vildvuxet över tid om man inte har en plan för hur man ska strukturera allt som skapas. Det gör att informationen ofta blir dubblerad och därmed riskerar att inte uppdateras och det gör det också svårare att hitta relevant information. Även om sökfunktionen är kraftfull så kommer det vara svårt att veta om informationen är relevant och uppdaterad om den finns på flera ställen.
Här är mina bästa tips för att skapa struktur i Confluence
Jag börjar alltid med en informationsinventering
Du har förmodligen redan idag ett ganska stort antal sidor i Confluence på andra ställen. Ett bra första steg är att göra en informationsinventering för att få en uppfattning om vilka dokument och filer som finns och var dessa lagras så att du i nästa steg kan börja kategorisera och strukturera det du identifierar. I din kartläggning kan du ställa dig följande frågor.
- Vem eller vilka producerar informationen?
- Vem eller vilka konsumerar informationen?
- Var finns informationen lagrad idag?
- I vilket format lagras informationen idag (pdf, word etc.)?
Du behöver inte kartlägga precis allt då detta ofta är en ganska omfattande uppgift men du behöver komma en bit för att hitta mönster.
Kategorisering av informationen
Du kommer förmodligen hitta en hel del information och dokument t ex krav, testfall, designdokument, releasenotes, mötesnoteringar och så vidare. Det kommer kort sagt vara högt och lågt, men börja med att skilja på vad som är tillfälligt arbetsmaterial och vad som behöver sparas och uppdateras över tid . Mötesnoteringar kan vara bra att spara för att dokumentera vad som beslutats men behöver oftast inte versionshanteras. Affärrsregler däremot behöver lagras på ETT ställe och versionshanteras så att man vet att det är uppdaterade och aktuella när man behöver göra förändringar.
Organisera efter förmågor och inte organisation
Systemdokumentationen kommer att leva över tid och det gäller därför att hitta ett sätt att organisera informationen som är relativt stabil. Att strukturera informationen baserat på organisation (t ex team eller avdelning) brukar inte vara så bra eftersom team och organisationer ofta förändras över tid. Det mest stabila jag har hittat är att organisera informationen utifrån det som brukar kallas kärnförmågor och stödförmågor.
Att hantera kundkommunikation är ett exempel på en kärnförmåga som kan ske på flera sätt via flera stödförmågor som till exempel e-post, telefoni eller kundportal. Dessa stödförmågor kan förändras över tid genom att man lägger till fler sätt att kommunicera eller genom att man byter ut den tekniska lösningen. Kärnförmågan kommer dock att vara stabil över tid.
Strukturera informationen
När du har skapat dig en bild av den dokumentation du har idag och hittat ett lämpliga kategorier att organisera den så är det dags att börja fundera på hur den ska struktureras. Här är det viktigt att skapa en struktur så att dina konsumenter enkelt hittar informationen de söker.
Det här steget är viktigt då du ofta behöver göra informationen tillgänglig för olika intressenter på olika sätt. Dina slutanvändare förmodligen inte tillgång till dina interna system utan kanske endast via en extern portal. Viss systemanvändardokumentation skall kanske bara vara tillgänglig för specifika interna grupper och då kan informationen behöva lagras på sidor som endast dessa har access till.
Det är också viktigt att man går igenom det som lagrats som arbetsmaterial i respektive teams space och flyttar det till den yta där den ska lagras långsiktigt. För teamen är det ofta praktiskt att ha dokumentationen “nära sig” men över tid blir det svåröverskådligt och särskilt om alla team har sitt eget sätt att dokumentera och dessutom utspritt på ett antal olika platser.
Använd makron för innehållshantering
När du har organiserat och strukturerat din information så kan du börja använda de makron för innehållshantering som finns i Confluence. Med hjälp av dessa kan du skapa sidor som är dynamiska och automatiskt hämtar data från t ex Jira. Du kan också organisera information med hjälpa av labels och page properties och på så sätt gruppera relaterad information.
Hur detta går till kommer att beskrivas i ett annat avsnitt