Technische documentatie schrijven

[BugBoy]

Niet direct een programmeervraag, maar ik denk dat hier de meeste mensen zitten met hetzelfde probleem en zou graag eens hebben over het schrijven van technische documentatie. De insteek is niet zozeer of het noodzakelijk is en hoeveel diepgang de documentatie moet hebben (dat kan per geval verschillen), maar hoe je de documentatie schrijft.

De verschillende opties
In de basis kun je op een aantal manieren documenteren:

• In Microsoft Word een requirements document, functioneel of technisch ontwerp schrijven. Veel bedrijven hanteren standaard templates voor verschillende documenten om je alvast op gang te helpen en het in de huisstijl te krijgen.
• Documenteren in een collaberate CMS (zoals bijvoorbeeld Atlassian's Confluence). Ook de WIKI pagina's van bijvoorbeeld Github of Gitlab zijn hier nog wel deels geschikt voor.
• Gegenereerde documentatie vanuit code (bijvoorbeeld Doxygen) laat ik even buiten beschouwing, want dat vind ik eigenlijk alleen geschikt voor referentie documentatie (zoals API beschrijvingen).

Het nadeel van documenteren in een tekstverwerker (zoals MS Word) vind ik dat je meer tijd bent om alles netjes in de juiste stijl te krijgen, dan dat je nadenkt over je tekst. Ook het toevoegen van code-voorbeelden is vaak lastig door allerlei stylings-issues. Ook zijn sequence diagrammen een regelrechte ramp. Je zou Visio kunnen gebruiken, maar €740 (per ontwikkelaar) is nogal duur voor af en toe een sequence diagram tekenen.

Documenteren in een tool als Confluence vind ik over het algemeen erg prettig, omdat je alles op een vaste plek hebt. Het nadeel zijn de repeterende kosten en dat je op een gegeven moment helemaal vast zit aan zo'n tool. Niet alle bedrijven willen dat of hebben de kosten er voor over. Daarbij zijn ook dit soort tools vaak vrij beperkt om goede sequence diagrammen te kunnen tekenen

Alternatief?
Ruim 20 jaar geleden (toen ik aan het afstuderen was) gebruikte ik altijd LaTeX voor mijn documenten. Eenmaal in het bedrijfsleven is dat eigenlijk helemaal verdwenen, maar het bestaat nog altijd en het heeft nog altijd de voordelen van toen (helaas ook nog de nadelen).

Een groot voordeel is dat je vooral bezig bent met tekst typen en vrijwel niet met opmaak en dat soort zaken. Helaas is het niet zo toegankelijk als bijvoorbeeld mark-down, maar het is wel veel krachtiger. Door middel van plug-ins kun je ook heel goed wiskundige formules, scheikundige vergelijkingen, maar ook sequence diagrammen, plaatjes, ... toevoegen.

Nu vroeg ik mij eigenlijk af wat jullie zoal gebruiken voor het documenteren en wat jullie ervaringen daar bij zijn.

[DiedX]

OneNote

[momania]

BugBoy schreef op dinsdag 27 maart 2018 @ 20:11:

• In Microsoft Word een requirements document, functioneel of technisch ontwerp schrijven. Veel bedrijven hanteren standaard templates voor verschillende documenten om je alvast op gang te helpen en het in de huisstijl te krijgen.

Wat beschouw je als waardevolle technische documentatie? Want imho is een ontwerp document nog geen documentatie.

Ik ga trouwens niet verder dan een readme.md in m'n repositories, wat code comments waar het nodig is.

De belangrijkste technische documentatie wordt trouwens vaak vergeten: runbooks. Code die niet draait is waardeloos

Kosten voor bepaalde tools zijn vaak trouwens ook niet echt een probleem hoor. De kosten voor zaken als Confluence, Visio, etc, vallen vaak ik het niet bij andere operationele kosten die een bedrijf maakt. Als je geld wilt besparen op de tools die je professionals nodig hebben, dan heb je grotere problemen.

[ Voor 18% gewijzigd door momania op 27-03-2018 20:24 ]

[Sebazzz]

Wij doen zelf altijd de documentatie als een set markdown bestanden in versiebeheer. Als voordeel heb je dat op een bepaalde revisie altijd kan zien wat de documentatie op dat punt was. Het is ook dichtbij de code en loopt minder kans vergeten te worden.

[Kwistnix]

Ik heb ervaring met Markdown voor o.a. vrij basaal README werk. Daarvoor voldoet het prima en de integratie met GitHub, Bitbucket etc. is erg praktisch. Voor documentatie die dit niveau ontstijgt ben ik inmiddels gewend aan Asciidoc i.c.m. Asciidoctor. Dat werkt goed genoeg naar mijn mening (ook voor diagrammen).

[BugBoy]

DiedX schreef op dinsdag 27 maart 2018 @ 20:13:
OneNote

Voor mij is OneNote eigenlijk meer een veredeld kladblok, waarin ik voor mijzelf veel bijhoud, maar ik vind het wat te ongestructureerd om project-documentatie in bij te houden.

Sebazzz schreef op dinsdag 27 maart 2018 @ 20:25:
Wij doen zelf altijd de documentatie als een set markdown bestanden in versiebeheer. Als voordeel heb je dat op een bepaalde revisie altijd kan zien wat de documentatie op dat punt was. Het is ook dichtbij de code en loopt minder kans vergeten te worden.

Ik ben ook wel erg van de mark-down, omdat we dat ook al gebruiken voor Gitlab. De kracht van mark-down is ook meteen de beperking en dat is dat je er niet zo heel veel mee kunt, zonder naar externe tools te moeten grijpen. Maar wellicht dat ik daar toch maar eens naar moet gaan kijken. Wellicht dat er wel tooling bestaat, waardoor je extensies kunt gebruiken binnen mark-down (en anders ga ik daar maar eens zelf mee aan de slag). Er zijn een aantal prima Javascript libraries, zoals js-sequence-diagrams en flowcharts.js die je prima zou kunnen combineren. Dan krijg je wel een soort van build voor je documentatie, maar daar kan ik nog wel mee leven.

[Sebazzz]

BugBoy schreef op dinsdag 27 maart 2018 @ 20:40:
[...]

Ik ben ook wel erg van de mark-down, omdat we dat ook al gebruiken voor Gitlab. De kracht van mark-down is ook meteen de beperking en dat is dat je er niet zo heel veel mee kunt, zonder naar externe tools te moeten grijpen. Maar wellicht dat ik daar toch maar eens naar moet gaan kijken. Wellicht dat er wel tooling bestaat, waardoor je extensies kunt gebruiken binnen mark-down (en anders ga ik daar maar eens zelf mee aan de slag).

Dat is het idee inderdaad, bijv. in combinatie met Gitlab. Voor schrijven gebruiken we een extensie voor Visual Studio of Markdownpad.

Achteraf hadden we misschien voor ReStructured Text moeten gaan, maar we hebben het nu eenmaal in Markdown geschreven.

[Sissors]

BugBoy schreef op dinsdag 27 maart 2018 @ 20:11:
Het nadeel van documenteren in een tekstverwerker (zoals MS Word) vind ik dat je meer tijd bent om alles netjes in de juiste stijl te krijgen, dan dat je nadenkt over je tekst.

Dan neem je imo of de stijl veel te serieus voor zoiets, of je templates zijn wel heel erg slecht. Een simpel template die goed gebruik maakt van Word features, en dus de standaard stijlen instelt voor het template, zou nauwelijks overhead moeten geven.

Dit in tegenstelling tot Framemaker, als we het toch over een kut pakket hebben zeg.

[nino_070]

Hangt er vanaf hoeveel je er moet typen: als het om veel documenten gaat is het zeker waard om een template te maken voor Latex, zeker als je daar al ervaring mee hebt.

[DHH]

BugBoy schreef op dinsdag 27 maart 2018 @ 20:11: Ook zijn sequence diagrammen een regelrechte ramp. Je zou Visio kunnen gebruiken, maar €740 (per ontwikkelaar) is nogal duur voor af en toe een sequence diagram tekenen.

Als gratis alternatief zou je draw.io kunnen gebruiken. Geen installatie of inloggen nodig en prima om 'af en toe' een diagrammetje te tekenen. Zitten tevens al een hoop templates in om direct mee te kunnen beginnen.

[xFeverr]

Ik heb inmiddels geleerd dat je een keer echt goed alles moet instellen in word, dat als een template moet opslaan en dat vervolgens gebruiken. Ik heb een template volledig in huisstijl, denk aan koppen, kleuren en tabellen, allemaal hetzelfde en default zoals de huisstijl dat wenst.

Je kan echt heel veel gekke dingen instellen. Ze willen bijvoorbeeld dat je 'kop 1' op een nieuwe pagina begint, om maar iets te noemen. Dat gebeurt dus nu ook automatisch. Zodra ik een kop 1 maak schiet hij gelijk naar een nieuwe pagina. Niet meer control+enter, niet meer lege pagina's ertussen halen, alles blijft op zijn plek. Zelfde als de hoofdstuknaam in de voettekst plaatsen en documenttitel in de koptekst: staat in mijn template en werkt gewoon.

Dus ik zou zeggen: word all the way!

[DJMaze]

LibreOffice
Goeie template maken met links in de ToC en gaan met die banaan.
Export naar PDF en je hebt dan ook de ToC in de PDF.

Of anders gebruik ik DocBook

[ Voor 11% gewijzigd door DJMaze op 28-03-2018 03:57 ]

[Hydra]

Wij gebruiken veel AsciiDoc. Met AsciiDoctor kan je daar hele boeken mee samenstellen, maar ook HTML output, en er zijn erg veel plugins voor SVG (kun je bijvoorbeeld Draw.io gebruiken) en PlantUML (voor plantUML diagrammen). Daarnaast ondersteunt 't natuurlijk ook gewoon plaatjes.

Wij hebben een systeem waarbij deze AsciiDoc/PlantUML documentatie bij de services zelf leeft en in een build pipeline samengevoegd wordt tot 1 overkoepelend document, het is dus een onderdeel van onze CI/CD pipeline. Door het bij de service te houden maak je het ook makkelijker om het het up to date te houden. Confluence pagina's raken altijd out-dated, om het nog maar niet over word documenten te hebben.

[ Voor 3% gewijzigd door Hydra op 28-03-2018 09:35 ]

[drm]

Hydra:
Wij gebruiken veel AsciiDoc. Met AsciiDoctor kan je daar hele boeken mee samenstellen, maar ook HTML output, en er zijn erg veel plugins voor SVG (kun je bijvoorbeeld Draw.io gebruiken) en PlantUML (voor plantUML diagrammen). Daarnaast ondersteunt 't natuurlijk ook gewoon plaatjes.

Wij hebben een systeem waarbij deze AsciiDoc/PlantUML documentatie bij de services zelf leeft en in een build pipeline samengevoegd wordt tot 1 overkoepelend document, het is dus een onderdeel van onze CI/CD pipeline. Door het bij de service te houden maak je het ook makkelijker om het het up to date te houden. Confluence pagina's raken altijd out-dated, om het nog maar niet over word documenten te hebben.

Helemaal mee eens. Ik ben zelf voorstander van Markdown, Textile of ReStructuredText als bron, i.c.m. Graphviz (.dot) voor diagrammen e.d.. Met een Makefile en pandoc als renderer heb je de build binnen no-time geautomatiseerd. Een heel groot voordeel hiervan vind ik dat je als developer niet van je workflow hoeft af te wijken om wijzigingen door te voeren: je neemt de documentatiewijzigingen gewoon mee in een merge request, en de documentatie is altijd coherent aan de huidige versie (mits daar ook op gereviewt wordt natuurlijk).

Als je dit op github toe wilt passen, kun je de Github wiki gewoon gebruiken als git repository (reponaam.wiki.git ) en heb je er meteen een webinterface bij voor mensen die het eng vinden om git te gebruiken, maar er zijn ook tooltjes waarmee je dat zelf kunt organiseren (zoals Gollum, of google even op "git backed wiki"). Dat sluit overigens het toepassen van merge requests in praktische zin wel weer uit, maar op Github kun je natuurlijk sowieso goed gebruik maken van de webinterface om wijzigingen voor te stellen.

Tot slot: omdat pandoc intern LaTeX gebruikt voor rendering van PDF's kun je customizen wat je wilt. LaTeX is niet supertriviaal maar wel weer plaintext (en dus makkelijk versionable) en met een beetje google-werk goed toe te passen.

Kortom: houd je documentatie plain text, doe versiebeheer in git en zoek tools die je handig vindt. Hou vooral het werkproces simpel, want als er iets is waar je gestoord van kan worden is het wel tekstverwerkers of wiki's die niet doen wat je willen. Hou een developer lekker in zijn eigen habitat.

[Yucon]

Goed topic. De valkuil is vaak dat documentatie verzand in het overtikken van databasetabellen in een word document. Inclusief veldtypes en lengtes. Tja, daar heb je niet veel aan en het is vreselijk bewerkelijk om dit goed te houden.

De uitdaging is echter om zodanig iets op te leveren dat het ook nuttig is voor de beheersorganisatie. Vaak schort het daar door allerlei praktische redenen aan, terwijl de basis vrij simpel is: vertel niet alleen wat iets doet, maar ook waarom het dat doet. Dan ben je al een heel eind. De tools zijn dan ineens minder belangrijk. Dat is ook wel een beetje de valkuil van gegenereerde documentatie. Leuk dat daarin dingen als tabelopbouw en zo ineens vanzelf gegenereerd worden.. maar het stuk dat nodig is om het voor de lezer begrijpelijk te maken schiet er vaak bij in. Terwijl juist dat de meerwaarde is.