[Algemeen]documenteren van applicatie

[pkouwer]

Ik heb een applicatie geschreven wat gedocumenteerd moet worden. Nu heb ik al een handleiding en commentaar in de code gezet. In hoeverre documenteren Tweakers hun applicatie, op welke wijze en in hoeverre is dit van (groot) belang.

[Verwijderd]

Oude WG poll

[thomaske]

Goede documentatie is (onder andere) van belang:
• Wanneer je met meerdere personen aan een project werkt
• Wanneer het moet van je baas
• de applicatie met broncode en al verkoopt en daarbij is overeengekomen dat het geheel gedocumenteerd is (ligt erg voor de hand)
• Bij grote applicaties waar je al snel het overzicht kwijt bent
• etc.

[ Voor 41% gewijzigd door thomaske op 02-12-2002 14:35 ]

[pkouwer]

Extra info: binnenkort ga ik van baan veranderen

[ Voor 1% gewijzigd door pkouwer op 02-12-2002 14:34 . Reden: tikfoutje ]

[momania]

Hangt er een beetje vanaf ook welke taal...in JAVA moet je goed commentaar in je code gebruiken en dan een keer javadoc runnen en klaar! technische documentatie...moet er alleen nog maar iemand naar de functionele documentatie kijken...

[pkouwer]

hmm, is VB. Functionele specs. zijn er al. gaat erom dat mijn collega het overneemt of aanpassingen realtief eenvoudig kan maken. Net zoals dat er eventueel probleempjes zijn.

[whoami]

Hmmm.... Er is hier al eens een topic over geweest, maar ik kan het niet zo direct terugvinden.

[Bobco]

Wat je documenteert hangt af van wie de documentatie moet lezen. Voor een programmeur is een overzicht (class of sequence diagram) in combinatie met zinvol commentaar in de source over het algemeen genoeg.

Voor een eindgebruiker moet de documentatie beschrijven hoe hij/zij taken uit kan voeren met de applicatie. Voor een functioneel beheerder moet de complete functionaliteit beschreven worden. Voor technisch beheerders moet er een applicatiehandleiding zijn die aangeeft hoe de applicatie gedraaid moet worden, wat de hard/software eisen zijn en hoe je bepaalde foutmeldingen moet interpreteren en afhandelen.

Kortom: er zijn net zoveel soorten documentatie als er rollen zijn....

In mijn beleving is documentatie voornamelijk van belang voor de overdraagbaarheid van een project. Dit kan gelden voor de overdracht van persoon naar persoon, maar zelf ben ik ook nog wel eens blij met documentatie die ik zelf geschreven heb omdat ik na 1,5 jaar echt niet meer weet wat ook al weer precies de bedoeling was van een bepaald stukje.

[pkouwer]

ik denk dat ik hier wel mee uit de voeten kan. Bedankt allemaal !!

[Verwijderd]

thomaske schreef op 02 December 2002 @ 14:33:
Goede documentatie is (onder andere) van belang:
• Wanneer je met meerdere personen aan een project werkt
• Wanneer het moet van je baas
• de applicatie met broncode en al verkoopt en daarbij is overeengekomen dat het geheel gedocumenteerd is (ligt erg voor de hand)
• Bij grote applicaties waar je al snel het overzicht kwijt bent
• etc.

Je kan je beter afvragen wanneer je geen documentatie moet maken. Ik denk dat je alleen geen/weinig documentatie nodig heb voor wat kleine hobby/test projecten.

Voor het project op school doen wij het zo:
pakket van eisen (pve)
functioneel ontwerp
technisch ontwerp
implementatie (commentaar in de code)
product documentatie

Het pakket van eisen is een opsomming van punten die het product moet bevatten en wat het juist niet bevat. Het functioneel ontwerp is een uitgebreide omschrijving van mogelijkheden. In het technisch ontwerp komt de structuur en opbouw te staan (gebaseerd op het functioneel ontwerp). De product documentatie is hetzelfde als het functioneel + technisch ontwerp alleen dan veranderd aan dingen die in de implementatie anders zijn gegaan.

Wij maken naast deze documentatie nog een testplan en een testrapport.

Met UML kan je volgens mij ook goede documentatie maken. Ik weet daar alleen weinig van af.

[FendtVario]

Het is verstandig om voor alles wat je maakt documentatie te maken. Een jaar geleden heb ik eens een applicatie gemaakt in delphi. Was een kleine applicatie (2 schermen, een rapportje en een zooitje tabellen). Nu moet er een uitbreiding komen en zit me wilt te zoeken wat alles deed.

Bij elke functie staat wel commentaar, maar ik moet met de debugger uitzoeken welke functie wat aanroept. Niet echt handig dus. Een use-case of seqeunce-diagram was hier dan wel weer handig geweest.

Documenteren is belangrijk, alleen is de tijd er niet altijd voor. Eigenlijk moet je dit documenteren voor een goed gebruik van de code later:
- functionele eisen
- niet functionele eisen
- klassen/gegevens diagram
- samenhang van code (hiervoor kun het beste achteraf een tool gebruiken)
- changelog (zelf bijhouden, of het commentaar van je versiebeheer programma uitprinten)

Naar mate een programma groter word moet je meer documenteren, afspraken maken en testplannen. Met goede functionele eisen en een goed testplan schrijf je de beste applicaties.

[pkouwer]

FendtVario schreef op 02 December 2002 @ 16:59:
- samenhang van code (hiervoor kun het beste achteraf een tool gebruiken)

klint goed, welke tools zoal? Is nieuw voor mij

[FendtVario]

delphi -> ModelMaker
java -> javadoc
allerlei (powerbuilder, java, sql) -> PowerDesigner

om een indruk te krijgen. Voor c/c++ zijn er ook tools, volgens mij zitten deze o.a. in KDevelop, maar weet niet zeker :-). Zoek maar eens naar een case-tool voor jouw favoriete programmeertaal, voor bijna alles is wat te vinden.

[jelmervos]

Wij maken gebruik van Unit Tests (Delphi). Mocht iemand iets ergens aanpassen kan ie het hele pakket testen en kijken of alles nog loopt en werkt zoals het moet werken. Dit is overigens een hulpmiddel. Natuurlijk zit er technische documentatie en gebruikers documentatie bij. En de CVS bevat commentaar.

[whoami]

[nohtml]

FendtVario schreef op 02 December 2002 @ 16:59:

- samenhang van code (hiervoor kun het beste achteraf een tool gebruiken)

Wat bedoel je precies met 'samenhang van code'?

Je moet gewoon consistent je coding guidelines (of die van het bedrijf) toepassen.

[Glimi]

[nohtml]

whoami schreef op 03 December 2002 @ 10:42:
Wat bedoel je precies met 'samenhang van code'?

Je moet gewoon consistent je coding guidelines (of die van het bedrijf) toepassen.

Daar bedoelt hij een UML class diagram oid mee. Iig iets waardoor je kan zien welke communicatie/relaties de classes onderling hebben.

En normaal gesproken doe je dat NIET met tools achteraf Maar is dat gewoon part of the design