Att skriva och dokumentera är inte allas favoritaktivitet, men det finns sätt att göra det både roligare, effektivare och snabbare. Patrik Fredriksson berättar.
Dokumentation och projekt är en härlig sak att diskutera. Alla har sin egen uppfattning om vad man ska ha dokumentation till, hur mycket som behövs, vad som inte behövs, vem som ska läsa, hur dokumenten ska skrivas och så vidare. I mjukvaruprojekt kan man stöta på alla varianter, från helt obefintlig till ett fullständigt hav av Worddokument som inte uppdaterats sedan 2002 (strax före lunch).
Det finns ett antal utmaningar som ställer till det för oss när vi ska spara undan information om det vi gör. Dokumentationen måste finnas i rimlig mängd för att man ska orka hålla den aktuell, och hålla den aktuell till en rimlig kostnad. Det måste vara lätt att hitta och söka i dokumentationen, risken är annars att vi inte hittar det vi söker när vi behöver det, eller att vi skapar dokument som redan finns.
Av olika anledningar kan det ofta vara praktiskt att versionshantera information och på det viset göra ändringar spårbara. Och så måste informationen vara lätt att komma åt när vi väl hittat den.
Mängden speciella program och läsare som behövs bör hållas så liten som möjligt. Till och med PDF, dokumentformatens dokumentformat, ställer till det när Windows helt står stilla medan vi tvingas läsa igenom alla tusen patent som visas under tiden Acrobat Reader startar.
Låt mig berätta en kort historia. En gång för många år sedan arbetade jag i ett litet projekt där, som så ofta, någon form av RUP ansågs användas. Nu när jag tänker efter fanns både användningsfall i Wordformat samt ett embryo till en SAD, så det stämmer nog. Projektledaren, som var en klok person, hade dock inte ramlat i fällan att försöka använda alla de möjliga dokumentmallar som RUP erbjuder, men var lite orolig för att det som verkligen var viktigt att dokumentera kanske inte heller skulle sparas till eftervärlden. Eftersom projektet till stor del var bemannat med konsulter var det säkert i stora delar en befogad oro. Projektledaren funderade ofta över detta problem. “Du måste skriva ner det där” kunde höras med jämna mellanrum i projektlokalen. En del blev nedskrivet, men mycket inte. Kanske var det blotta tanken på vad Officegemet skulle göra med den inklistrade skärmbilden, installationsbeskrivningen eller Oraclesupportkonversationen från MetaLink som gjorde att det helt enkelt inte blev av.
Så en dag fick jag ett tips från en kollega på ett annat projekt om att testa en wiki. De körde en version som hette JSPWiki i sitt projekt, så jag laddade ner den och installerade. Efter det smygtipsade jag några av de mer nyfikna personerna i projektet, inklusive de som var minst intresserade av att dokumentera. Nästan på en gång dök det upp den ena intressantare saken efter den andra på wikin. Det dök upp ny information om saker jag inte visste om sedan tidigare, och en del av det jag själv skrivit på wikin blev på något magiskt sätt korrigerat när det var fel. Systemet introducerades för resten av projektet och fler och fler började använda wikin för allt möjligt. Projektnyheter, planerad frånvaro bland projektmedlemmarna, leveransnoteringar, kontaktinformation till olika personer – allt hamnade på wikin. Till och med användningsfallen blev wikifierade och Worddokumenten slängdes. All information blev korslänkad och automatiskt sökbar, och efter några uppgraderingar av wikimjukvaran blev informationen dessutom versionshanterad. Wikin användes till slut av hela projektet, inklusive testare, kravinsamlare och utvecklare.
Wow, vilken grej. Efter denna framgångssaga har jag tillsammans med kollegor och projektmedlemmar i olika projekt utvecklat idén om en projektwiki. Inte sällan går själva introduktionen till på liknande sätt som ovan, lite gerillaartat. De flesta har lätt att direkt ta till sig konceptet, men personer som lagt mycket tid på att skapa fina Worddokument kan känna ett lite större motstånd. Det är kanske inte så konstigt, en wikifiering av dokumenten innebär ofta en fulifiering eftersom mängden frihetsgrader vad gäller grafiska layoututsvävningar begränsas. Men oftast övertygar fördelarna i slutet.
Så här långt borde det vara klart att wikin är det bästa som hänt världen efter espresson (möjligen med undantag för den ankformade USB-dammsugaren för tangentbord[1]). Men vad är en wiki egentligen?
En wiki är en webbplats där användare enkelt kan lägga till och ändra innehållet. Fokus är typiskt på innehållet och möjligheterna för användarna att påverka formatering och design är oftast begränsade. Detta håller tröskeln låg, alla kan enkelt delta utan omfattande utbildning i verktyget! Det finns idag mängder av olika wikiimplementationer som är mer eller mindre lätta att komma igång med.
Den första wikin någonsin skapades av Ward Cunningham, och fokuserar på människor, projekt och mönster i mjukvaruutveckling. Ward sökte ett enkelt sätt att skapa en dynamisk webbplats där alla användare snabbt kunde ändra och lägga till information och nya sidor. Med hjälp av CGI-teknik byggde han en webblösning för detta som han valde att kalla för Wiki Wiki Web, eller Wiki kort och gott. Sedan dess har fenomenet spridit sig över världen. Idag finns en uppsjö av wikivarianter och webbplatser som baserar sig på wikiteknik. Den mest kända är kanske Wikipedia[2].
Själva ordet wiki kommer från uttrycket “wiki wiki”, som är Hawaiianska för “snabb” (eng “quick”).
Olika wikiimplemenationer erbjuder olika nivåer av funktionalitet, men följande tycker jag att man kan betrakta som någon form av lägsta standard för att en wiki ska börja bli riktigt användbar som projektdokumentsystem:
- Enkel att använda, för alla! En webbläsare och en mycket kort introduktion ska räcka för att börja använda wikin, oavsett om man är teknikvan eller inte.
- Begränsad möjlighet till formatering, fokus på innehåll, inte på form. Alltför avancerade redigerings- och formateringsfunktioner gör bara wikin svår att använda, och stjäl fokus från innehållet. Därmed inte sagt att wikin inte ska ha ett attraktivt utseende, tvärtom!
- Sökbar. En wiki blir ofta snabbt full av information, så för att det ska gå att hitta det man letar efter krävs en snabb och exakt sökfunktion.
- Versionshanterad. Bra om man vill se vem som gjort vad och ha möjlighet att rätta fel och misstag på ett enkelt sätt.
- Stöd för “Recent changes”. Det ska vara lätt att se vad som senast ändrats och många wikiimplementationer har en “Senast ändrad”-funktion som snabbt ger en överblick över vad som hänt den senaste tiden på wikin. Vissa implementationer erbjuder även RSS-stöd.
- Versionshantering av bilagor. Ibland måste man bilägga ett dokument, Wikiimplementationer bör ha effektivt stöd för detta.
- Utbyggbar. Många wikiimplementationer erbjuder möjlighet för användarna att skriva egna insticksprogram, detta kan vara ett relativt enkelt sätt att addera verktyg man saknar.
- Snabb. Detta är 2006. Man ska inte behöva vänta på datorer.
Om man väljer en populär wikimjukvara med stöd för externa insticksprogram så finns det goda möjligheter att utveckla den till att bli ännu mer användbar. Har man tur finns det till och med redan ett insticksprogram utvecklat av någon annan som gör det man önskar. Jag har till exempel byggt mycket enkla program för att övervaka och styra den kontinuerliga integrationen av kod och för att visa de senaste förändringarna i versionshanteringssystemet. En stor röd “Build Failed”-text på wikins förstasida tenderar att få igång även den mest motsträviga byggsabotör. Dessutom är det rätt så trevligt att kunna bygga en fullständig, testad och dokumenterad version av det system man utvecklar genom att klicka på en knapp på wikin.
När projektet börjar leverera kan det vara lämpligt att låta kundsupport eller motsvarande organisation få tillgång till wikin och fortsätta utveckla innehållet, man skulle till och med kunna låta slutkunden ta del av wikin.
Det behöver alltså inte vara speciellt svårt att samla viktig dokumentation runt ett mjukvaruprojekt. En wiki tillhandahåller ett lättanvänt och kraftfullt stöd för att samla och underhålla information. Om du inte redan har gjort det så är du förstås sugen på att sätta upp en egen wiki nu. Det finns många olika att välja på, både kommersiella och fritt tillgängliga. Nedan följer några förslag. Personligen har jag använt JSPWiki med framgång. Lycka till!
Fotnoter
- http://www.engadget.com/2005/11/23/usb-duck-keyboard-vacuum/
- Wikipedia är ett Wikibaserad flerspråkigt fritt tillängligt uppslagsverk som underhålls av frivilliga användare. Enligt Wikipedia själva består det av mer än 2 550 000 artiklar (varav mer än 900 000 på engelska). Coolt. Om Wikipedia:
- http://en.wikipedia.org/wiki/Wikipedia
- Wikipedia på engelska: http://en.wikipedia.org/
- Wikipedia på svenska: http://sv.wikipedia.org/
Lär dig mer om wiki
- jspwiki – skriven i Java http://www.jspwiki.org/
- Confluence – kommersiell wiki från Atlassian http://www.atlassian.com/
- MediaWiki – wikimjukvaran som används för Wikipedia http://www.mediawiki.org/wiki/MediaWiki
- XWiki http://www.xwiki.org/xwiki/bin/view/Main/WebHome
- VQWiki http://www.vqwiki.org/
- FitNesse – En wikiimplementation som även är ett ramverk för acceptanstest! http://fitnesse.org/