Net een reden te meer om goed te documenteren wat hij wel dacht nodig te hebben zodat het (zo snel mogelijk) duidelijk is dat er iets verandert en het budget en de planning mee kunnen aangepast worden.
M'n bek valt open van wat ik als verheelrlijking van waterval zie hier.
Alle requirements van te voren bekend? Ik dacht (hoopte) dat er toch ondertussen geen IT-er meer was die in die leugen geloofde...
I denk dat er voor sommigen hier een wereld opengaat als ze zich eens in agile zouden verdiepen. Welcome change!
En dat betekent dus dat je er van te voren vanuit gaat dat de requirements veranderen gaande het project.
Agile is leuk, maar net zo goed een probleem. Enkele mogelijke issues:
- de klant zelf is helemaal niet agile. Voor een klant betekent zelf mee agile zijn typisch een interne meerkost. Er wordt immers veel vaker feedback gevraagd, soms testing door echte gebruikers enz. Daar wordt dan geen tijd en budget voor voorzien waardoor het in praktijk toch een waterval is (extern, intern hoeft dat niet)
- de klant denkt dat agile zijn betekent dat hij op ieder moment alles kan vragen zonder enige impact op planning en budget want we zijn toch allemaal agile wat toch betekent dat we op ieder moment alles kunnen aanpassen en toch iedere deadline die 6 maand geleden gesteld is kunnen halen. Een klant ziet agile als een mogelijkheid om extra's te vragen midden in het project, zonder extra kosten of budget. Features of onderdelen laten vallen om de deadline te halen (wat ook onder agile valt) kan dan typisch niet.
- De overhead tijdens een project is veel hoger en het uiteindelijke project is minder voorspelbaar. Iedere keer er een wijziging gebeurt moet dit goed bijgehouden worden om wijzigingen in planning en budget te verantwoorden. Bij een klassiek waterval project zit alle overhead in het begin en is het daarna ieder zijn eigen ding doen. En dan uiteraard de overhead op het einde: klant die zegt dat het niet doet wat hij wil vs implementator die zegt dat het alles doet wat afgesproken was. Meestal hebben beiden dan ook gelijk en is niemand tevreden. Agile is vaak hetzelfde maar ipv enkel op het einde ontevreden te zijn zijn we dat al ergens middenin het project.
Beide systemen hebben hun voordelen, maar ook nadelen en ik ben zeker geen fervente aanhanger van het waterval model maar het managen van een software project is een vaak onderschatte oefening.
Heel veel hangt af van het type klant waar je mee werkt. Overheids-instanties, grote bedrijven enz. kunnen heel vaak niet agile meewerken. Komt voor een deel ook door hun financieringsmodel. Alles (inclusief eindresultaat) moet op voorhand gekend zijn en van een budget kan niet afgeweken worden.
Eén van de redenen waarom software projecten vaak mis lopen is omdat de complexiteit verborgen blijft voor de meeste stakeholders. Wanneer je een brug bouwt en de ruwbou staat er en men komt tot de conclusie dat die eigenlijk een meter hoger moest zijn, dan snapt iedereen dat die moet afgebroken worden en je eigenlijk opnieuw begint. Wanneer de reling groen is en achteraf rood mooier zou zijn, dan snapt ook iedereen dat dit "maar" schilderen is.
Wanneer iemand een aanpassing vraagt aan software is de impact van die aanpassing echter zelden duidelijk voor de persoon die die aanpassing vraagt. Agile betekent dan ook gewoon dat je halfweg de bouw van de brug met een vrachtwagen probeert of je er effectief onder kan. Indien ja, gaat alles gewoon volgens plan. Indien nee, dan weet je het gewoon al halfweg dat het fout gegaan is en hoef je niet te wachten tot het einde van het project om tot die conclusie te komen. Je kan dus uiteraard sneller inspelen op dat probleem, maar dit betekent niet dat het niet duurder zal zijn. Het zal in het beste geval minder veel duurder zijn dan in het waterval model. En dat beseft niet iedereen.
Je gaat dan ook vanzelf afstappen van het absurde idee dat van t evoren opgestelde documenten ooit als (technische) documentatie kunnen dienen, trouwens. Om dan maar een beetje ontopic te komen.
Wat je van tevoren maakt valt onder ontwerp. Documentatie hoort te documenteren wat er daadwerkelijk gebouwd is, niet wat ooit iemand bedacht heeft als idee.
Dus zelfs als uit je documentatie blijkt dat bepaalde requirements niet of verkeerd zijn geimplementeerd hoort dat in je documentatie. Sterker nog, het bewijst het nut van goede documentatie.
Hier ben ik het helemaal mee eens.
Waar een design document (of dat nou URS, FO of TO is) als leidraad voor je code kan helpen, is het je code die de documentatie op moet leveren. Ontwerpdocumenten en systeemdocumentatie zijn niet hetzelfde. Ik weet uit ervaring dat ontwerpen niet alleen achterhaald maar zelfs afschuwelijk frustrerend zijn als ze als technische systeemdocumentatie gebruikt moeten worden.
Mijn standaard antwoord op de vraag om documentatie is dan ook altijd dat de documentatie pas komt als mijn implementatie gedaan is. Dat is namelijk het eerste moment waarop ik die implementatie kan documenteren in plaats van ontwerpen.
Simpel voorbeeldje, dat ik een GUID opsla als string hoeft in geen enkel design document te staan en heeft geen enkele functionele impact. Technisch zorgt het wel voor vraagtekens, en is het dus nuttig om te documenteren dat ik dat doe vanwege compatibiliteit met de gekozen mobiele database die geen GUID datatype kent.
Dat is technische documentatie (die belangrijk is ook, om te voorkomen dat een ijverige DBA in SQL Server 2012 mijn nchar(16) in GUIDs verandert!) die je nevernooit in een ontwerp terug hoort te zien komen (veel te laag niveau!).
Hell, in dat ontwerp hoeft niet eens vermeld te zijn dat er technische sleutels gebruikt worden.
Een dergelijk onderscheid zie ik helaas vaak niet gemaakt worden. Iedereen wil technische documentatie, maar er is nooit tijd (lees: budget) voor. Dus zoeken we drie jaar later in een URS op wat we denken dat de code zou moeten doen, of, more likely, we kijken in de code of we de business rules kunnen achterhalen.
Wat uit bovenstaande stukje en ook de hele discussie tot nu toe blijkt is dat er heel veel soorten documentatie zijn. En de TS heeft niet heel duidelijk aangegeven over wat soort documentatie deze discussie zou moeten gaan. Wat wordt er trouwens bedoelt met code in dit topic: echt de programmeercode, software componenten, volledige toepassingen?
Wat ik al zien voorbijkomen heb (zelf verzonnen termen, niet exhaustief en niet op elk project allemaal van toepassing)
- low level code documentatie: wat doet code (wat mij betreft onnodig, code zelf moet idd leesbaar zijn, tenzij er om een of andere reden iets speciaal gedaan wordt)
- code documentation: korte tekstuele uitleg van een specifiek algoritme bv
- method documentation: wat doet een specifieke methode?
- high level code documentation: bv omschrijving van wat de taken/functies zijn van een klasse of package
- API documentatie: indien het een API aanbiedt aan externe software: hoe werkt dit, wat doet het allemaal
- architectuur documentatie: wat is de opzet van de software, welke componenten, waarom bepaalde keuzes
- installatie & configuratie documentatie: wat is er nodig om iets geïnstalleerd te krijgen
- beheer documentatie: welke onderhoudstaken zijn er nodig, wat als er iets niet functioneert, moet een bepaald deel dan herstart, is er een volgorde waarin dat moet gebeuren
- gebruikers-handleiding: voor de eindgebruiker
1-5: zijn zeer technisch en voor en door de developers
5-6: voor development en door de architect geschreven
7-8: voor de application managers, worden vaak gecombineerd, echter niet altijd (bv specialist installer die SAP komt installeren en configureren, algemene beheerstaken worden door een lokale admin uitgevoerd)
9: voor eindgebruikers
(ja 5 wordt bewust 2 maal opgenomen)
In praktijk is er echter altijd te weinig tijd voor de documentatie, bijna op elk van de omschreven niveaus. (maar dit is al een veel te lange post ondertussen)
/u/262310/ava.png?f=community)
/u/147751/avatar455992_1.gif.png?f=community){kind=avatar}
:strip_exif()/u/56159/archer.gif?f=community)
:strip_icc():strip_exif()/u/51489/heforshe_logo_detail.jpg?f=community){kind=logo}
/u/3813/100_8985_ICON2.JPG?f=community)
/u/220490/bombcut.png?f=community)
/u/12668/hydra.png?f=community)
). Documentatie voor "andere developers" is vooral de code zelf. En dan heb je nog de functionele specificaties (wat moet het doen) en de daaruit volgende technische specs (hoe doet het dat) waarbij de laatste in heel veel gevallen praktisch overgeslagen wordt.
):strip_exif()/u/91205/avator_pavo.gif?f=community)
/u/155722/Looneytunes.png?f=community)
/u/142011/crop65b383c6c6c2f_cropped.png?f=community)
:strip_exif()/u/26373/anim4.gif?f=community)
"). Als het ooit zover komt hoop ik ze wel te kunnen overtuigen van mijn visie 
.
/u/39688/AnnoAvatarSmall.png?f=community){kind=avatar}
:strip_exif()/u/13818/episodebutler_60x60.gif?f=community)