Levande och Agil dokumentation

Det Agila manifestet förespråkar ”Working software over comprehensive documentation” och de flesta Agila metoder indikerar att man skall fokusera på fungerande funktioner högre än dokumentationen. Att man bara skall skapa precis så mycket som man behöver tycker jag kan vara missvisande. Det finns vissa fall då Agila utövare inte fokuserar alls på dokumentation och detta kan resultera i att resultatet inte blir kvalitativt och svårt att förvalta över tid.

Enligt min mening så borde man tänka mer Agilt kring dokumentation och även tänka varje segment av dokumentation som en potentiell byggsten i en större kontext så man kan återanvända enskilda fragment av dokumentation i olika sammanhang och med olika ingångar.

När man skriver sin kod så borde man även skriva förklaringar som går att återanvända även dessa från olika ställen, detta kan göras i Visual Studio med hjälp av XML kommentarer genom verktyg som GhostDoc för att stubba ut och delvis automatisera denna process. Dessa kommentarer kan sedan användas i andra delar av koden när man kallar på den i form av tooltips och man kan även exportera den och skapa automatiserad systemdokumentation som hjälper till att synliggöra och förklara hur koden och tester är uppbyggt.

Genom att använda en fullfjädrad Wiki för sin dokumentation så kan man även bygga dokumentation från alla delar av projektet och från olika vinklar där alla som bidrar fyller på med små byggstenar som är ämnade för återanvändning. Detta skiljer sig rejält från den traditionella formen av dokumentation där man ofta fyller i en förformaterad mall i exempelvis Microsoft Word och det blir mer av ett race för att fylla i innehåll runt ett skelett som tyvärr inte är så enkelt att återanvända och svårt att ens söka reda på.

En viktig faktor att tänka på att sökbarheten i dokumentationen, det måste gå att hitta rätt och ju snabbare man kan hitta ju mindre meningslöst letande blir det. Om man har dokumentation på flera ställen så kan man tjäna mycket på att bygga upp sökindex som söker på alla ställen och fronta detta med ett sökfönster. Genom att bygga upp dokumentation med logiska namnrymder (namespace) så borde man kunna söka i delar av dokumentationen och få upp endast relevant information.

Lägger man samman dessa två former av dokumentations rutiner tillsammans med en Team Foundation Server (TFS) som alla deltagare samarbetar kring så kan man få till ett stort dokumentationsvärde tillsammans med kommunikationskraften från TFS. Detta erbjuder en åtråvärd transparens kring hela livscykeln med många Agila fördelar. Genom att ha minimalt med ”waste”, långsiktighet och modultänk i dokumentationen så minimerar man tiden för nya projektmedlemmar att komma in i projektet och dokumenten blir en naturlig del av utvecklingsarbetet.

Att ha för lite dokumentation kan vara väldigt kostsamt då det tar längre tid för nya att sätta sig in och riskerna med att det intellektuella kapitalet sitter inne i huvet på deltagarna och finns då inte tillgängligt om personer inte är på plats. Dessa mjuka argument är svåra att räkna på men om man tänker hela applikationers livscykler så blir det viktiga faktorer att vikta in för att få rätt kvalitet på det man eftersträvar.

Det svåra i kråksången är ju att få till rutiner och systemstöd som underlättar insamling och transparens kring meta informationen i utvecklingsarbetet. Microsoft är den ledande leverantören på ALM lösningar men samtidigt den ledande leverantören av det traditionella dokumentations plattform i form Office (Word, Excel, Powerpoint). En tankegång kring detta är ju om Microsoft krigar på två fronter. Nya element i Office som OneNote och Storyboarding i PowerPoint indikerar ju att Microsoft försöker integrera Office med vinkling åt det Agila tänket. Samtidigt som den gamla skolan lever kvar parallellt i Office så kanske det blir någon form av identitetskris kring användandet av Office för dokumentationsarbete. Ser man till helheten i Microsoft lösningar med SharePoint, Team Foundation, Visual Studio och Office så har man en riktigt solid plattform för att leverera just Agilt värde. Arvet kring traditionell dokumentens metodiker i dessa verktyg kan dock visa sig vara hinder för att övertyga på värdet att använda just dessa verktyg.