Blogg | Knowit

Gästinlägg: Dubbeldokumentation är fienden, inte dokumentation

Skriven av require | Jun 1, 2014 10:00:00 PM

När jag håller kurs eller seminarium talar jag ofta om att kravarbete handlar om kommunikation. Möten, interaktioner, minnesanteckningar, presentationer, specifikationer – allt syftar till att mellan människor kommunicera vad som ska byggas och hur det ska fungera.

Från ax till limpa kommer då olika typer av kravbeskrivningar fylla olika syften. Vi talar exempelvis om mål, processkartor, informationsmodeller, kontextdiagram, user stories, användningsfall, UI mockups, systemövergripande kvalitetskrav, etc. Ja, även i en agil värld använder vi nedtecknade ord och bilder!

Vid något tillfälle i ett projekt rör vi oss från kravbeskrivningar till mer detaljerade lösningsbeskrivningar: arkitektur, tjänster, moduler, klasser, etc. Detta tar vi fram och kommunicerar under projektets gång. Och ofta bevarar vi dem lite längre än vi trodde. Det visar sig ju ofta att det trots allt inte är så tokigt att bevara beskrivningar av hur vi tänkte – på annat format än programkod.

Det är utmärkt och nödvändigt med olika perspektiv. Men när vi tillför ytterligare beskrivningar från olika perspektiv så uppstår ett problem. Plötsligt kan vi uppleva hur befintliga beskrivningar upprepas på flera ställen. Ibland är delar kopierade rakt av. Ibland är delar beskrivna i en annan form.

 

Har du redundans i dina beskrivningar?

 

Denna dubbeldokumentation utgör ett kommunikationsproblem. Det skapar osäkerhet i projektet om vad som gäller. När arkitektens systemkarta delvis överlappar med kontextdiagrammet så börjar man undra vilken beskrivning som är den rätta (spårbarhet, någon?). För att motverka detta försöker olika roller i projektet synka sina artefakter och kvalitetssäkra dem med granskningar och ömsesidiga uppdateringar. Plötsligt har dokumentationen blivit viktigare än interaktion och kommunikation. Och det kostar.

Problemet är vanligare i projekt där projektmedlemmarna jobbar deltid i projektet, har särskilda roller (kravanalytiker, arkitekt, testare, programmerare) eller sitter på olika ställen. Hur gärna vi än vill undvika detta så blir vi ibland tvingade av rådande förutsättningar. Det må vara besvärande för den som vill praktisera agilt arbetssätt fullt ut men bara för att det blir krångliga konsekvenser behöver vi inte fullständigt släppa det agila förhållningssättet!

Vi måste vara på det klara med att när vi beskriver systemkrav/lösning så rör vi oss på en skala mellan behov och programkod. Därför räcker det inte att fokusera på endast de klassiska kravartefakterna. Vi måste titta på allt som beskriver lösningen.

Jag tror att ett par enkla riktlinjer kan hjälpa oss:

  1. Alla beskrivningar utgör ett gemensamt verktyg för att bygga rätt system.
  2. Även eliminering av innehåll i en beskrivning är ett naturligt steg i att detaljera krav och lösning.

Dags för ett exempel.

I ett projekt arbetar kravanalytikern Mikael med att förtydliga ett systemscenario baserat på en user story. Enligt scenariot ska det vid ett visst tillfälle skickas information till ett externt system. Mikael identifierar vilken information det är och beskriver den i användningsfallet. Självklart beskriver Mikael inte mer än vad som är intressant ur ett verksamhetsperspektiv. Tillsammans med representanter från verksamheten kommer han fram till att det är namnadress och ansökt belopp.

I samband med detta gör arkitekten Sofia sin analys och identifierar att det behövs en ny web service. För att få koll på denna web service i form av ett ”integrationskontrakt” mellan system så beskriver Sofia hur tjänsten ska utformas. I detta ingår att beskriva vilken information som ska skickas mellan systemen. Det finns bland annat en header som består av schemaidentifiering, sessionsinformation, avsändare, tidsstämplar, etc. – saker som måste till för att säkerställa att kommunikationen sker enligt rådande riktlinjer och tillräcklig säkerhet. Därtill har vi det viktiga innehållet med namnadress och ansökt belopp.

Utgående från riktlinje 1 ser vi nu att i de gemensamma beskrivningarna finns samma krav på två ställen. Om vi vid något tillfälle vill förtydliga att adress innebär en valfri C/O-adress, en gatuadress, ett postnummer och en ort så måste vi uppdatera våra beskrivningar på två ställen (jo, man kan fortsätta hänvisa till ”adress” och definiera det i en central definitionslista men det blir kanske lite väl komplex och löser inte riktigt problemet).

Ur ett klassiskt perspektiv är kraven styrande och designbeskrivningen ska uppdateras baserat på kraven. Det är klokt att ha en sådan princip men dubbeldokumentationen ökar risken för fel och det tar onödig tid. Inte särskilt lean om vi ska använda ett annat trendigt uttryck.

Ett mer pragmatiskt sätt är att när vi detaljerar lösningen och tillför fler beskrivningar så väljer vi också att aktivt förändra innehållet i de beskrivningar vi redan har. Lättrörligt förändrar vi vårt arbetssätt.

I det här fallet tar vi bort informationsbeskrivningen från scenariot och låter det stå i beskrivningen av web servicen. Vän av ordning kan invända att det är olika perspektiv och att det är högst lämpligt – för effektivare kommunikation – att låta beskrivningen av informationen stå kvar i Mikaels scenario. En rimlig invändning men sett ur ett helhetsperspektiv är det faktiskt inte tillräckligt värdebringande och inte tillräckligt effektivt. Följande positiva effekter får vi i stället om vi tar bort det ur scenariot:

  1. När vi läser användningsfallet tvingas vi att titta i den beskrivning som ska säkra att rätt information når ett annat system. Det betyder att beskrivningen av webservicen aldrig får ett eget liv. Istället får den ett värde.
  2. Vi tvingas att göra beskrivningen av web servicen tydlig ur ett verksamhetsperspektiv – inte bara ur ett tekniskt. Detta är en kvalitetssäkring i sig.
  3. Vi kan se i scenariot att lösningen inte detaljerats mer. Om informationsbeskrivningen ligger kvar i scenariot så har vi inte identifierat någon ny eller befintlig web service som ska bära informationen. När vi gjort det kan vi ange det med en kommentar i scenariot.
  4. När vi skriver nya scenarion så kan vi enkelt hänvisa till redan beskriven information. Det är nämligen större chans att vi aktivt uppdaterar ett integrationskontrakt än ett scenario, inte sant?
  5. Vi ökar chansen för att vi har en gemensam bild av vad som ska lösas i stället för att olika personer i projektet skapar sig en egen bild.
  6. Vi undviker att slösa tid på en filosofisk diskussion om vad som är krav och vad som är design.

Varje gång vi upprepar information så riskerar vi att olika personer får olika perspektiv och syn på vad som ska byggas. Vi ska alltså alltid sträva efter att dokumentera tillräckligt mycket vid varje givet tillfälle. Detta är en agil princip som, för att den ska fungera, måste genomsyra hela projektet. Principen betyder i förlängningen att vi inte bara utökar våra beskrivningar utan också rensar i dem.

De två riktlinjerna kan kontinuerligt appliceras på alla tillfälliga eller permanenta beskrivningar som vi tar fram i ett utvecklingsprojekt eller i en förvaltning. Det ökar kommunikationen mellan projektdeltagarna vilket i sin tur ökar chansen för att vi bygger rätt system!

Eller vad tror du?

/Johan Natt och Dag, verksamhets- och kravanalytiker