Documentatie: van hoofdpijndossier naar gestroomlijnd proces

Bij veel organisaties is het aanleggen en onderhouden van documentatie een hoofdpijndossier. Documentatie is vaak verouderd of nog erger, helemaal niet aanwezig. Dit moest anders kunnen, vonden we bij JAM-IT. Daarom hebben we een aanpak ontwikkeld waarmee documentatie een gestroomlijnd proces wordt.

Wat documentatie zo'n hoofdpijndossier maakt

Ontwikkelaars vergeten het te updaten

Er worden constant updates gedaan en nieuwe features toegevoegd aan de applicatie. Maar de documentatie updaten? Dat zit vaak niet in het proces van de ontwikkelaar. In de praktijk denkt de organisatie eens in de zoveel tijd: we moeten onze documentatie weer eens updaten. En dan wordt de boel bijgewerkt. Het resultaat: een groot deel van de tijd is de documentatie verouderd.

Voor de gebruikers van de app is het een doolhof

Zo gaat de zoektocht naar documentatie er bij veel apps zo ongeveer aan toe:

• Je moet de app verlaten en naar een aparte website met documentatie
• Daar moet je op zoek naar wat je nodig hebt, via de zoekfunctie of door lijsten met artikelen door te spitten
• Om er vervolgens achter te komen dat de documentatie niet meer klopt
• En de klantenservice te contacteren

Als gebruiker absoluut geen pretje.

De oplossing? Documentatie als integraal onderdeel van de applicatie

Bij JAM-IT hebben we het roer omgegooid. We zien documentatie niet langer als een losstaand element, maar als een integraal onderdeel van onze applicaties. Hoe werkt dat in de praktijk?

Hulp op het juiste moment, op de juiste plek

Stel je voor: je bent bezig in een applicatie en hebt even wat uitleg nodig. Je klikt op een vraagteken bij het veld waar je mee bezig bent en krijgt direct de relevante informatie te zien. Jij kunt weer verder.

Het resultaat?

• Gebruikers vinden veel sneller wat ze zoeken
• De applicatie wordt beter gebruikt, omdat meer mensen de tips voor gebruik zien
• Je klantenservice krijgt minder werk, want gebruikers lossen meer zelf op

Ontwikkelaars schrijven en updaten de documentatie binnen de app

Wij hebben het schrijven van documentatie volledig geïntegreerd in het ontwikkelproces. Passen ontwikkelaars iets aan in de app? Dan kunnen ze de documentatie binnen hun ontwikkelomgeving aanpassen of toevoegen. Ze hoeven de documentatie dus niet meer los aan te leggen op een externe documentatiesite.

Het resultaat?

• Documentatie updaten wordt een natuurlijk onderdeel van het ontwikkelproces
• Het aanleggen en updaten van documentatie wordt nooit meer vergeten
• Ontwikkelaars besparen tijd omdat ze niet hoeven te switchen tussen verschillende systemen

Updates in de app leiden automatisch tot updates op de documentatiesite

Voor gebruikers is het soms toch fijn om alle documentatie op één plek te hebben. Daarom hebben we nog steeds een losse website met documentatie. Maar het vullen en updaten van die website hebben we vrijwel volledig geautomatiseerd. We hebben tools ontwikkeld die de in-app documentatie automatisch extraheren en verwerken in de documentatiesite.

De voordelen?

• De documentatiesite is altijd up-to-date met de laatste versie van de applicatie
• Er is geen extra werk nodig om de documentatiesite bij te werken
• Verminderde kans op fouten door handmatige updates

Voorbeeld: zo pakken we dit aan binnen JamOps

In JamOps (onze DevOps oplossing voor Mendix) kunnen gebruikers vanalles configureren. Bij elke configuratie-optie staat een tooltip om de gebruiker op weg te helpen. De gebruiker ziet deze tooltip direct als hij op het vraagteken klikt en hoeft hiervoor niet eerst te graven in allerlei documentatie.

Wil een gebruiker een overzicht van alle documentatie? Geen probleem. Op de documentatiesite van JamOps zijn alle tooltips terug te vinden. Deze worden automatisch ingeladen. En past een ontwikkelaar een tooltip aan in de applicatie? Dan wordt de documentatiesite ook automatisch geüpdatet.

Hetzelfde geldt voor uitleg over rules. In JamOps zijn allerlei rules verwerkt (daarmee wordt de code gecheckt) en de ontwikkelaars van JamOps schrijven daar altijd een uitleg bij. Deze uitleg wordt ook weer automatisch ingeladen op de documentatiesite van JamOps.

Documentatie hoeft geen hoofdpijn te veroorzaken

Door documentatie te integreren in ons ontwikkelproces en gebruik te maken van automatisering, hebben we een systeem gecreëerd dat tijd bespaart, fouten voorkomt en de kwaliteit van onze documentatie verhoogt. Het resultaat? Blijere ontwikkelaars en klanten die de app beter kunnen gebruiken.

Wil je meer weten over hoe wij omgaan met kwaliteit en documentatie? Lees dan ook ons artikel over onze ISO 27001 certificering.