WikiDoc

Etter å ha presentert på NoBug nå i september med et foredrag om dokumentasjonsløsningen WikiDoc tenkte jeg at jeg kunne supplere med en blogg post hvor jeg går litt nærmere inn på WikiDoc og hvordan denne løsningen fungerer i dag og hvilke planer vi har for fremtiden.

Introduksjon 

Først kan vi starte med en kort introduksjon til WikiDoc for de som ikke har hatt gleden av å høre om dette verktøyet før. WikiDoc er en dokumnentasjonsportal basert på et Wikipedia oppsett som bruker automatisk generert dokumentasjon gjennom tredjeparts programvare for å vedlikeholde og strukturere teknisk dokumentasjon. Løsningen er utviklet som et verktøy for å hjelpe utviklere, prosjekter og kunder med å strukturere, administrere, tilgjengeliggjøre og vedlikeholde dokumentasjon på en enkel måte. Portalen slik den fremstår i dag gir brukere muligheten til å legge inn manuelt skrevet og vedlikeholdt dokumentasjon side om side med automatisk generert dokumentasjon basert på kildekode og deployede løsninger.

Løsningen er brukt i flere prosjekter hos Communicate og det arbeides med å gjøre kildekoden Open Source slik at andre også kan få glede av løsningen, samt at det kan skapes et community rundt videreutviklingen av portalen og tilhørende løsninger.

Grunnstruktur 

Teknisk sett er WikiDoc en hybrid mellom en wiki og en dokument-parser. Løsningen består av tre separate komponenter som jobber sammen for å gjøre dokumentasjonsprosessen så automatisert og enkel som mulig. De tre komponentene er en dokumentør, en Web-App og en Scheduled Uploader.

Dokumentøren er selve hjernen til WikiDoc. Den bruker resultatet fra tredjeparts programvare slik som BizTalk documenter og Swagger til å genere «wiki-like» dokumentasjon per miljø som deretter lastes opp i en utskiftbar lagringsløsning og derfra sammenstilles og vises til brukeren via Web-Appen. Har man flere enn et miljø opprettes en lagringsinstans for hvert miljø. Man velger en «hovedinstans» i Wikiens konfigurasjon ved førstegangs bruk som inneholder fellesfiler for alle miljøene. I de løsningen som kjører i dag er Azure Storage valgt som lagringsløsning og du ender da opp med en «Container» per miljø. I en tradisjonell SQL database ville man typisk hatt en kolonne som inneholder en switch på miljø eller en tabell per miljø.

Hver enkelt automatisk generert side som vises til brukerne av WikiDoc består dermed av en manuell- og en automatisk del. Den automatiske delen lages av dokumentøren og lastes inn i lagringsløsningen. Den manuelle delen opprettes når den automatiske delen hentes av Web-Appen og vises til brukeren. Når brukeren da velger å legge inn manuelt innhold for å nærmere beskrive den automatiske delen av dokumentasjonen lagres den manuelle delen i lagringsløsningen. Den manuelle delen er lik for alle miljøer. Prosessen er nærmere beskrevet i diagrammet under:

wikidoc_diagram
Et diagram over Wikiens struktur

Filene som dokumentøren bruker for å oppdatere dokumentasjonen generes som sagt av tredjeparts programvare i noen tilfeller, men vi har også sett oss nødt til å lage noen egne regler for parsing av informasjon fra kildekode. Per i dag så har vi laget egne løsninger for WebJobs og C# kode. Den informasjonen som kommer fra tredjepart blir forespurt generert av Scheduled Uploader programmet som laster alt opp i lagringsløsningen slik at dokumentøren får tilgang til filene. Scheduled Uploader kjører gjerne en eller flere ganger i døgnet avhengig av hvor fort man vil ha endringen synlige i WikiDoc portalen.

Portalen 

Når all dokumentasjonen er parset, generert og lastet opp i lagringsløsningen vises alt som en helhet i WikiDoc portalen. Selve portalen er bygget opp med et tankesett om at informasjonen som finnes der skal være lagdelt etter viktighet for å gi høyere tilgjengelighet og for å senke terskelen for å sette seg inn i prosjektet som dokumenteres. Jeg liker å kalle denne tankegangen de tre nivåene av gjenfinnbarhet.

Det første nivået er forsiden av portalen. Her har kan man dynamisk legge inn «thumbnails» som består av et bilde, en lenke og en beskrivelse.  Disse boksene blir da det øverste nivået av gjenfinnbarhet og representerer det innholdet som er viktigst for noen som setter seg inn i systemet for første gang eller informasjon som er essensiell for systemet på andre måter og som alle skal ha umiddelbar tilgang til.

Det andre nivået av gjenfinnbarhet er menyen. Den gir mer finkornet tilgang til kategorisert informasjon. Som dere ser på bildet over så representerer menyen overhengende komponenter eller kategorier i to nivåer. Halve menyen er manuelt vedlikeholdt og opprettet, mens den andre halvdelen er automatisk generert av dokumentøren. I bildet over starter den automatiske delen fra og med «Biztalk» punktet.  De komponentene som støttes for automatisk dokumentasjon er per i dag BizTalk, API, Webjobs, Database og C# kode (ny versjon er på vei her). Disse dukker da opp som hvert sitt menyelement eller som underelementer av andre komponenter. C# dokumentasjonen fungerer som et slikt underelement.

demowiki
Wikiens forside

Det siste nivået av gjenfinnbarhet er søkefunksjonaliteten. Dette er en helt vanlig søkefunksjon som har to varianter; et hurtigsøk og et mer tidkrevende søk. Det mer tidkrevende søket viser såkalte «snippets» av hva man søker etter, altså et lite uttrekk av siden der ordet man søker etter ble funnet. Denne funksjonaliteten krever derimot høy prosesseringskraft og vi valgte derfor å implementere et raskere søk som fjernet denne funksjonaliteten. Man kan bytte søk ved å bruke profilsiden inne i Wikien.

Disse tre nivåene av gjenfinnbarhet er med på å gjøre WikiDoc til noe unikt i dokumentasjonssammenheng. Dette prinsippet lar de som dokumenterer velge hva som er mest relevant og gir dem muligheten til å rettlede lesere inn til de delene som gir mest utbytte for minst innsats.

Veien videre

Denne bloggen dekker ikke all funksjonaliteten til WikiDoc, men gir et raskt overblikk over grunnstrukturen. Mer avansert funksjonalitet og enkeltkomponenter kan jeg gjerne ta opp i et senere innlegg hvis det skulle være ønskelig.

I henhold til veien videre for selve WikiDoc så er planen å bygge videre på portalen for å lage enda bedre gjenfinnbarhet og struktur. Dette skal vi oppnå ved å lage bedre menystruktur, metadatafunksjonalitet for lagringsløsningen og bedre søkefunksjonalitet. Vi skal også ta en grundig kikk på hvordan automatisk genererte komponenter knyttes inn i dokumentasjonen og lage en modulbasert løsning slik at nye komponenter kan knyttes opp uten kjennskap til hovedprosjektene. Når koden forhåpentligvis ender opp som Open Source håper jeg at utviklere som er interessert i løsningen melder sin interesse og at vi kan drive dette videre sammen.

Avslutningsvis 

Hvem har vel ikke sittet og stirret på metervis av Word dokumenter på et filområde og latt seg selv gå vill i titler og sider på jakt etter det man trodde var grunnleggende informasjon? Denne hverdagen er nå på vei ut og vi har prøvd å gjøre dokumentasjon til noe som ikke bare skal være enkelt, men også direkte morsomt. Fordi portalen er bygget som en nettside har man alle moderne verktøy å støtte seg på i dokumentasjonsprosessen dette kan være alt fra video og dynamiske diagrammer til animasjoner, bilder og linker. Dette gjør dokumentasjonen spennende og lettfattelig på et nivå som Word-dokumenter aldri vil kunne oppnå, men det er ikke bare de «kule» funksjonene som gir en enklere dokumentasjonshverdag, men også et system hvor struktur og vedlikehold av dokumentasjon er en selvfølge. Dagene for distribuerte filområder med navnestandard er over og inn kommer en hverdag hvor endringer i kildekoden påvirker hvilke sider som genereres og hvor strukturen for dokumentasjon bestemmes og modereres uten menneskelig innblanding.

Legg igjen en kommentar