Genereren end-user documentatie in ontwikkelproces

[Orphix]

Hallo,

Als er iets is wat de afgelopen jaren is veranderd op het gebied van software engineering is het wel de opkomst van agile development; kort door de boch het regelmatig opleveren van software in relatief korte slagen. Dit gaat hand-in-hand met diverse technieken waaronder automatic builds, unit testing, etc. Veel van deze tools zijn nog erg gericht op de ontwikkelaar. Traditionele unit tests zijn prima geschikt om kleine stukjes code te testen, maar het wordt al een stuk lastiger wanneer use-cases of interfaces getest moeten worden.

Ik ben op zoek naar een methodiek of tool die mij kan ondersteunen bij het generen van eindgebruiker documentatie. Dus geen documentatie van de API, maar de help interface die de gebruiker van het systeem te zien krijgt. Denk bijvoorbeeld aan tutorials, uitleg interface elementen, wellicht zelfs video's, etc.

Eindgebruiker documentatie wordt vaak relatief los van het ontwikkelingsproces gebouwd. Enerzijds omdat het wellicht beter is als dit door iemand anders wordt gedaan dan de software engineer zelf. Anderzijds ook omdat de tooling er op dit moment nog niet is. Hoe hou je de eindgebruiker documentatie en de applicatie zelf synchroon? Hoe kan je garanderen dat de documentatie overeenkomt met wat de applicatie doet, en correct is?

Ik open dit topic omdat ik graag ervaringen wil horen van anderen hoe zij dit aanpakken, en de tooling die gebruikt wordt. En daarnaast ook om een discussie te starten of jullie het ermee eens zijn dat eindgebruiker documentatie nog steeds als een los kindje wordt gezien, en wat hier aan gedaan kan worden.

[Verwijderd]

Ik moet je eerlijk zeggen dat ik geen idee heb hoe je end-user documentatie kunt genereren vanuit code. Even snel denkend zou je zeggen dat je end-user documentatie gerelateerd is aan je UI. Je zou dus met bepaalde annotations in je UI code wel IETS kunnen doen. Toch denk ik dat je het best je documentatie zelf kunt schrijven, omdat je toch een soort van logische indeling moet maken die niet voor de programmeur, maar voor de eind-gebruiker klopt.

Ik zou zelf kiezen voor een goeie versie nummerering van de handleiding. Gewoon als deel van je release ook je handleiding updaten. Daarnaast is 't gewoon zaak om je versiebeheer op orde te hebben zodat je in je logs kunt zien welke nieuwe features je toevoegt, en welke dingen zijn veranderd

Maar goed, da's puur speculatie, ik hou me nooit zo bezig met user documentatie Misschien dat anderen betere ideeen hebben

[F_J_K]

Eindgebruiker documentatie wordt vaak relatief los van het ontwikkelingsproces gebouwd. Enerzijds omdat het wellicht beter is als dit door iemand anders wordt gedaan dan de software engineer zelf. Anderzijds ook omdat de tooling er op dit moment nog niet is.

En ten derde omdat een gemiddelde ontwikkelaar niet iemand is die goede eindgebruikerdocumentatie kan schrijven.

Anyway: Writing End-User Documentation in an Agile Development Environment

[MisterBlue]

In een goed agile proces heb je al user stories als basis. Alles wat je bouwt is gekoppeld aan een user story en als je bij het aftikken van een user story ook nog een update gedaan doet van een bijbehorende handleiding heb je een goed moment om te kijken of de zaken nog synchroon lopen.
Uiteraard heb je dan nog geen mooie indeling en zo, het blijft nog mensen werk om er iets goed werkbaars te maken.
Je kunt met een wiki en tagging dit dan wel goed zoekbaar maken voor de eind gebruiker. Vind dit in elk geval een betere manier dan te wachten tot iemand de tijd neemt om een word document bij te werken.

[ Voor 7% gewijzigd door MisterBlue op 01-11-2007 15:28 ]

[Niemand_Anders]

End-user documentatie schrijven tijdens het agile development process is niet verstandig. Want als de boel wordt omgegooid omdat het niet naar verwachting van de klant is, kun jij met je documentatie weer opnieuw beginnen.

Wij schrijven de end-user documentatie pas zodra het (deel) project als milestone op de test omgeving akkoord is bevonden en dus bevroren. De documentatie schrijvers gaan dan pas dat onderdeel beschrijven en zelfs video's van belangrijke handelingen maken.

Daarnaast schrijven bij ons developers nooit end-user documentatie. Developers beschrijven wel functioneel en technisch wat zij gaan bouwen (zelfs de API moet zijn uitgewerkt). De API uitwerking wordt dan als handvat bij development gebruiker. Het volledig documenteren van de API gebeurt wel via commentaar in de code. Documentatie voor en door developers zeg maar.

Daarnaast hebben developers vaak ook een hele andere kijk op user interfaces en wat wel of niet duidelijk is. Dat heeft vooral te maken dat developers veel technische zaken als vanzelfsprekend beschouwen zoals ook in vorige reacties opgemerkt.

Daarnaast moet de end-user documentatie er ook gewoon verzorgd uitzien omdat de documentatie vaak het eerste is wat de gebruikers van het systeem onder ogen krijgen. Als ze daar een negatief gevoel bij krijgen, slaat dat vaak over naar het gebruik van het systeem zelf.

[MisterBlue]

Wij schrijven de end-user documentatie pas zodra het (deel) project als milestone op de test omgeving akkoord is bevonden en dus bevroren. De documentatie schrijvers gaan dan pas dat onderdeel beschrijven en zelfs video's van belangrijke handelingen maken.

Dit is geen garantie dat de documtatie niet meer hoeft te wijzijgen. Bij agile processen kan functionaliteit nog wijzigen in volgende iteraties na oplevering (in productie) van vorige iteraties.
Dit door gewijzigde inzichten aan de hand van het echt gebruik in productie of doordat men bewust heeft gekozen om minimale functionaliteit met hoge business value eerst te doen.

Dit kan lastig zijn voor de eindgebruikers zijn en daarom is het belangrijk dat iedereen beseft wat agile werken betekend, de organisatie moet er gereed voor zijn.

[Orphix]

Verwijderd schreef op donderdag 01 november 2007 @ 14:49:
Ik moet je eerlijk zeggen dat ik geen idee heb hoe je end-user documentatie kunt genereren vanuit code.

Het hoeft ook niet rechtstreeks uit de code gegenereerd te worden. Echter zou je eind-gebruiker documentatie wel moeten overeenkomen met wat je code doet.

Even snel denkend zou je zeggen dat je end-user documentatie gerelateerd is aan je UI. Je zou dus met bepaalde annotations in je UI code wel IETS kunnen doen. Toch denk ik dat je het best je documentatie zelf kunt schrijven, omdat je toch een soort van logische indeling moet maken die niet voor de programmeur, maar voor de eind-gebruiker klopt.

Klopt. Hoe beschrijf je bijvoorbeeld gebruikershandelingen in de UI. Ergens ligt dit niet ver af van de code (klik hier, klik daar, zie resultaat), maar tegelijkertijd is het zo high-level dat je dit niet zomaar kunt neerschrijven in een classe die je maakt. Er moet dus een andere beschrijving/notatie/structuur komen die enerzijds wel dicht bij de code zelf ligt, maar tegelijkertijd high-level genoeg is voor de eindgebruiker. Een word document voldoet dus niet.

F_J_K schreef op donderdag 01 november 2007 @ 14:53:
En ten derde omdat een gemiddelde ontwikkelaar niet iemand is die goede eindgebruikerdocumentatie kan schrijven.

Dat bedoelde ik eigenlijk ook met mijn 'enerzijds'

Anyway: Writing End-User Documentation in an Agile Development Environment

Bedankt voor de link. Ik merk al dat ik een beetje op de verkeerde termen heb gezocht. Als ik meer in het technical writer hoekje ga zoeken kom ik meer relevante blogs en artikelen tegen. Opvallend is wel dat dit vrij recente artikelen zijn, de combinatie van technical-writers icm agile development is zeker nog niet uitgekristalliseerd.

MisterBlue schreef op donderdag 01 november 2007 @ 15:25:
In een goed agile proces heb je al user stories als basis. Alles wat je bouwt is gekoppeld aan een user story en als je bij het aftikken van een user story ook nog een update gedaan doet van een bijbehorende handleiding heb je een goed moment om te kijken of de zaken nog synchroon lopen.
Uiteraard heb je dan nog geen mooie indeling en zo, het blijft nog mensen werk om er iets goed werkbaars te maken.

Als je user stories kan vertalen naar code, kan je code dan ook vertalen naar user stories? Waar ik bang voor ben is dit: een user story wordt opgesteld, de code wordt geschreven en documentatie geschreven. In de loop der maanden/jaren verandert de code ongetwijfeld, maar verandert de oorspronkelijke user story en de documentatie ook automatisch mee? Waar is de koppeling tussen code en documentatie als het eenmaal geimplementeerd is. Als ik in mijn versiebeheer een logitem zet waarin bijvoorbeeld staat 'Changed locking process, authorization is now required before modification of articles'. Dan zal dit een impact hebben op de oorspronkelijke user story, aangezien de gebruiker nu extra stappen zal moeten ondernemen. Maar is dit zo duidelijk?

Ik ben me er bewust van dat het mensenwerk is, maar mensen zijn feilbaar en die wil ik het liefst zo min mogelijk in het proces betrekken Wat ik wil zeggen is, tuurlijk als je zeer goede controlerende feedback hebt in je proces of in je organisatie dan kunnen zulke problemen ondervangen worden. Maar mijn vraag is of we dit wellicht een stapje kunnen automatiseren: net als static typing al problemen aangeeft voordat je een stuk software uitvoert (maar niet de oplossing geeft!), zou ik me ook kunnen voorstellen dat een 'end-user documentation compiler' waarschuwing kan geven wanneer code en documentatie niet meer synchroon lijken te lopen.

Niemand_Anders schreef op vrijdag 02 november 2007 @ 11:20:
End-user documentatie schrijven tijdens het agile development process is niet verstandig. Want als de boel wordt omgegooid omdat het niet naar verwachting van de klant is, kun jij met je documentatie weer opnieuw beginnen.

Dat je opnieuw moet beginnen lijkt me zeer sterk. Je schrijft je programmatuur hopelijk ook niet elke keer opnieuw als de klant niet helemaal tevreden is Dat is uiteraard het idee van agile: continue feedback en continu kleine aanpassingen. Ik zou end-user documentatie daar ook onder scharen.

Wij schrijven de end-user documentatie pas zodra het (deel) project als milestone op de test omgeving akkoord is bevonden en dus bevroren. De documentatie schrijvers gaan dan pas dat onderdeel beschrijven en zelfs video's van belangrijke handelingen maken.

Volgens mij is er een kamp mensen die zegt 'end-user documentatie komt altijd een iteratie _na_ oplevering van de code'. En in het andere kampt zegt men 'end-user documentatie kan prima tegelijk ontwikkeld worden.'. Ook heb ik voorbeelden gelezen waarbij de technical writer samenwerkte met de ontwikkelaar om uiteindelijk de juiste functionaliteit te krijgen. Soort van pair-programming dus, maar dan tussen technical writer <-> programmer.

Daarnaast moet de end-user documentatie er ook gewoon verzorgd uitzien omdat de documentatie vaak het eerste is wat de gebruikers van het systeem onder ogen krijgen. Als ze daar een negatief gevoel bij krijgen, slaat dat vaak over naar het gebruik van het systeem zelf.

Vooral bij webapplicaties merk ik dat een help vaak gewoonweg ontbreekt. Er zijn maar weinig webapplicaties waar ik mee werk die een goede context-sensitive help functie hebben. Het is nog steeds een ondergeschoven kindje.

Als ik het kort mag samenvatten:

• Scheiding tussen ontwikkelaar <-> writer is over het algemeen best practice met goede redenen. Ik denk dat we het daar wel eens over zijn.
• End-user documentatie in dezelfde iteratie of een-iteratie-later. Hier is men minder unaniem over. Ik denk dat het ook een verschil is in de organisatie van het ontwikkelingsproces: zie je de technical writers als onderdeel van je ontwikkelingsteam of gooi je het product na elke iteratie 'over de muur' naar de writersafdeling om er een mooie documentatie voor te maken.
• Er is een paradigma gat tussen de ontwikkelde code en de user stories, of user tasks. Is er een vorm van documentatie, of taal, die deze brug kan dichten? Kunnen bijvoorbeeld integrations tests de leidraad vormen voor documentatie? Is dit (gedeeltelijk) te automatiseren?

[MisterBlue]

Maar mijn vraag is of we dit wellicht een stapje kunnen automatiseren: net als static typing al problemen aangeeft voordat je een stuk software uitvoert (maar niet de oplossing geeft!), zou ik me ook kunnen voorstellen dat een 'end-user documentation compiler' waarschuwing kan geven wanneer code en documentatie niet meer synchroon lijken te lopen.

De gebruikers interactie van een applicatie verander je niet uit je zelf als ontwikkelaar. Daar is een issue/user story voor vanuit de business. Deze is geregistreerd in je ticket systeem. De code die je commit is hieraan gekoppeld (zorg ervoor dat je repository geen code accepteerd zonder issue number) en als in de workflow nog een stap komt voor bijwerken van documentatie of dat je in elk geval een vlag kunt zetten, dan heb je je waarschuwing a la static typing.

Als je ook bij houdt op basis van welke revisie de laatste documentatie gemaakt is kun je met een query op de code repository alle changelogs sinds dien opvragen en reviewen of deze invloed hebben op de documentatie. Als je trac gebruikt, kun je hiervoor de timeline view gebruiken.
Je zou een tool kunnen maken waarbij iemand de changesets moet afvinken op het bijwerken van documentatie. Een reviewproces aan het eind van een iteratie waarbij elke committer naar zijn commits kijkt en controleert of deze in de documentatie is bijgewerkt.