[Alg] Documentatie, waar te plaatsen?

[Sebazzz]

Een onderwerp waar ik graag met mijn collega developers hier op GoT over wilt sparren: Documentatie, waar dient deze geplaatst te worden, en in welk formaat.

Sinds kort zijn wij echt goed begonnen met documenteren, als onderdeel van een meer professionele werkwijze. Niet dat wij eerst niet documenteerden, maar ik ben er nu persoonlijk een stuk meer op naar het sturen. Eerst unit tests, daarna CI, toen CD en nu documenteren. Alles in stapjes

Het gaat mij hier voornamelijk om technische documentatie met betrekking tot een softwaresysteem. Denk hierbij aan UML diagrammen, database ontwerp, en technische uitleg hoe een onderdeel van een systeem in elkaar zit. Denk bijvoorbeeld aan hoe versiebeheer van entiteiten in bepaalde software in elkaar zit.

Recent is door o.a. mijn inspanningen in de documentatie bij ons de discussie opgelaaid over waar deze documentatie te plaatsen én in welk formaat.

Op het moment maak ik de documentatie in Markdown (en ik schrijf ze in Markdownpad), maar dat terzijde). Deze documentatie stop ik vervolgens in versie beheer. Voor UML diagrammen gebruik ik de ingebouwde tools in Visual Studio. Ook deze diagrammen check ik in versiebeheer. Mijn argumenten voor dit is dat de documentatie, gezien deze zwaar technisch van aard is, dichtbij bij de code moet zijn en met de code mee moet leven. De drempel om documentatie bij te werken moet zo laag mogelijk zijn. Ook valt dankzij versiebeheer makkelijk terug te vinden hoe een onderdeel van het systeem in elkaar zat in een bepaalde punt in tijd. Beide formaten zijn sowieso text-based dus makkelijk te diff-comparen.

Het bedrijf waar ik werk is een grote accountant en de regel is daar om de documentatie en deliverables van een project in een rigide mappenstructuur te plaatsen, ver weg, diep in een share. Omdat wij als ontwikkelaars een apart gescheiden netwerk van het bedrijfsnetwerk hebben, kunnen wij indien aangesloten niet op het bedrijfsnetwerk komen. Eén van mijn collega's wilt graag dat ik juist mijn documentatie in de genoemde mappenstructuur plaats, waardoor we voor elk softwareproject moeten afvragen hoe we bij de documentatie moeten komen. Mijn tegenvoorstel is om aan het 'einde' van elk project de documentatie te exporteren en bij de deliverables te voegen, al ben ik ook van mening dat zulke technische documentatie niet daar thuishoort.

Hoe kijken jullie hier tegenaan, en hoe ontwikkelen jullie (technische) documentatie?

[ Voor 7% gewijzigd door Sebazzz op 09-04-2015 21:43 ]

[Low-Tech]

Naar mijn mening technische documentatie altijd binnen versiebeheer houden. In de vertrouwde rigide mappenstructuur puur een verwijzing naar de juiste locatie binnen het versiebeheer zetten.

[Avalaxy]

Sebazzz schreef op donderdag 09 april 2015 @ 21:40:
Op het moment maak ik de documentatie in Markdown (en ik schrijf ze in Markdownpad), maar dat terzijde).

offtopic:
Klein tipje: in web essentials zit ook markdown support zodat je vanuit Visual Studio kunt markdownen

Als het om indeling gaat zou ik voor markdown en andere files denk ik gewoon een mapje Docs maken naast het mapje Src, waar de source code in zit. Dan heb je beiden bij elkaar (zoals het imho hoort) en staat het beiden in versiebeheer.

Een andere optie waar je naar kunt kijken is om Ghostdoc te gebruiken om een help file te builden, dan heb je MSDN-achtige documentatie voor je code en heb je bovendien gelijk in je code zelf documentatie waar intellisense mee overweg kan. Je kunt met Ghostdoc ook gewoon conceptuele documentatie stoppen, dat hoeven niet alleen maar functiebeschrijvingen te zijn. Het is wel retetraag om die files te builden, maar dat kan je CI server voor je regelen met een aparte nightly configuratie.

Aangezien je de files ook nog ergens anders moet zetten: kun je niet als onderdeel van je CI-proces de documentatie kopiëren naar een secundaire locatie? Dan staat het zowel waar jij wilt als waar zij willen.

[ Voor 8% gewijzigd door Avalaxy op 09-04-2015 22:00 ]

[chaoscontrol]

Sharepoint?

[Sebazzz]

@Avalagy Nope. Gescheiden netwerken, dus onmogelijk.

@chaoscontrol Kan je daarop uitweiden?

[Kwistnix]

Wij gebruiken hier een combinatie van markdown voor eenvoudige - veelal technische - documenten, zoals een README of een changelog. Voor documentatie die wat meer opsmuk vereisen gebruiken we LibreOffice (OpenDocument XML) en alles wat extern gaat exporteren we daarin als PDF. We zijn zijdelings aan't kijken of we misschien iets met AsciiDoc kunnen gaan doen.
Alle documentatie heeft een plaatsje binnen het project en gaat mee de Git repo in.

[ Voor 10% gewijzigd door Kwistnix op 10-04-2015 11:01 ]

[Blubber]

Wij gebruiken Sphinx, documentatie is in RST geschreven. De source (in Python) bevat voor api functies een header met RST documentatie die door Sphinx wordt opgepikt, daarnaast is uitgebreidere uitleg en ontwerp info in /docs gezet in RST formaat. De docs wordt automagisch gegenereerd met Sphinx op de CI omgeving en op een dev webserver gezet.

Afgezien van implementatie details zou ik de documentatie zeker bij de source houden, in je source control systeem, zodoende heb je altijd de actuele code en bijbehorende docs.

[Matis]

Voor UML gebruiken wij PlantUML en dat duwen we dan weer in een Wikimedia-server.

Met de kennis van nu, zouden we het in een VCS (bij ons git) hebben gegooid. Dat doen we dan nu ook voor nieuwe projecten.