Een softwareontwerpdocument maken

De meeste softwareontwikkelaars haasten zich liever door het proces van het documenteren van ontwerpeisen heen, of vermijden het zelfs helemaal als het mogelijk is. Ze willen het liefst meteen beginnen met het bouwen van de code en doorgaan met het uitrollen van het eindproduct. Echter, het bouwen van een heel softwareproduct of een set daarvan, zonder een software ontwerpdocument kan rampzalig zijn. Een software-eisen document, of een software ontwerpdocument, is een solide verzameling specificaties en verschillende details die dienen als blauwdruk voor het hele project.

Een softwareontwerpdocument legt duidelijk vast wat de vereisten, verwachte functies, gewenste functionaliteiten, enz. van de software zijn en wordt een referentiepunt dat het hele softwareontwikkelingsteam kan volgen. En als de software voor een externe klant wordt gebouwd, is de software ontwerpdocument wordt nog belangrijker omdat het ervoor zorgt dat zowel de klant als de softwareontwikkelingsbedrijf het eens zijn over de deliverables zodat er geen verwarring ontstaat tijdens het project of op het moment van de release/overdracht. Daarom is het documenteren van ontwerpeisen en het maken van software ontwerpdocumenten een must voor elke software ontwikkelaar, ook al lijkt het schrijven van een software ontwerpdocument misschien een saaie klus.

Laten we eens snel bekijken wat een softwareontwerpdocument is en welke essentiële elementen een dergelijk document moet bevatten.

Wat is een Software Design Document?

Een software ontwerpdocument is bekend onder verschillende namen zoals een software ontwerpspecificatie of technische specificatiedocumenten of een software eisendocument. Het is een zeer gedetailleerd document dat de algemene architectuur beschrijft van een softwareproduct dat gemaakt moet worden. Volgens de IEEE is een software ontwerpdocument “een beschrijving van software gemaakt om analyse, planning, implementatie en besluitvorming te vergemakkelijken”. Zie het als een gids of een blauwdruk die de softwarearchitecten (de programmeurs en ontwikkelaars) helpt begrijpen hoe ze een softwareproduct moeten bouwen op basis van een reeks technische vereisten.

En wie maakt dit noodzakelijke document? Het zijn meestal de projectmanagers en ervaren softwareontwikkelaars die een softwareontwerpdocument maken en ervoor zorgen dat alle belanghebbenden de specificaties van de software begrijpen.

Waarom hebben we documenten voor softwareontwerp nodig?

Stel je eens voor wat er zou gebeuren als je aan een lange autorit zou beginnen zonder navigatie of een kaart als gids? Of een architect die besluit een heel huis te bouwen zonder een blauwdruk als leidraad voor hem en zijn team? Software ontwerpdocumenten zijn een belangrijke manier om iedereen die betrokken is bij het product in het proces te betrekken. Het is bedoeld om iedereen te laten begrijpen wat mogelijk is, wat niet mogelijk is en het systeem dat ontworpen zal worden door ze een stabiel referentiepunt te geven dat alle onderdelen van de software beschrijft en hoe ze zullen werken.

Voor het interne ontwikkelteam is het een geweldige manier om de hele systeemarchitectuur duidelijk te plannen. Ontwikkelaars en projectmanagers kunnen elk mogelijk obstakel of hiaat doornemen dat het project kan belemmeren. Het brengt projectgerelateerde informatie samen en maakt het mogelijk om alle belangrijke vragen tussen belanghebbenden en ontwikkelaars te bespreken.

Een software ontwerpdocument zorgt ervoor dat het product wordt gebouwd dat voldoet aan de behoeften en op één lijn ligt met wat was afgesproken voor de ontwikkeling van de software. Het dient ook als een controlepunt voor klanten om te bevestigen of het softwareontwikkelingsbedrijf heeft geleverd zoals gepland.

Wat beïnvloedt het type softwareontwerpdocument?

Het type documentatie dat een software-ontwikkelingsteam zal maken, zal sterk afhangen van de gekozen software-ontwikkelingsmethodologie. Dat klopt. We hebben het over de traditionele Watervalmethode en de meer recente Agile-methode. Ze zijn allemaal uniek qua begeleidende documentatie.

De watervalmethode is lineair, met duidelijke doelen voor elke ontwikkelingsfase. Wanneer deze aanpak wordt gebruikt voor softwareontwikkeling, wordt er veel tijd besteed aan productplanning in de eerste fasen van het project en wordt er gedetailleerde documentatie gemaakt voordat de volgende ontwikkelingsfasen beginnen. Ontwikkelteams creëren een uitgebreid overzicht van de belangrijkste doelstellingen en kunnen het werkproces plannen, waardoor een nauwkeurige budgettering en tijdsinschatting mogelijk zijn. Zoals de afgelopen tien jaar is gebleken, is de watervalmethode natuurlijk niet effectief voor langetermijnontwikkeling, omdat deze geen rekening houdt met mogelijke veranderingen en onvoorziene omstandigheden onderweg.

De agile methode voor softwareontwikkeling is gebaseerd op nauwe samenwerking tussen ontwikkelaars en de klant en biedt zowel schaalbaarheid als de flexibiliteit om sneller op veranderingen te reageren. De agile methode is zeer iteratief en elke iteratie, d.w.z. een grote verandering in de specificaties of verbetering/nieuwe vereisten, omvat planning, analyse, ontwerp, ontwikkeling en testen. De agile methode vereist geen uitgebreide documentatie aan het begin omdat het project veel veranderingen met zich meebrengt terwijl het zich ontwikkelt. Het idee is om documentatie te produceren met informatie die essentieel is om vooruitgang te boeken wanneer dat het meest zinvol is.

Laten we nu eens kijken naar wat een ideaal softwareontwerpdocument zou moeten inhouden.

Wat komt er in het Software Design Document?

Dit zijn de details die een typisch softwareontwerpdocument bevat:

Titel:

Titel van het document

Inleiding:

Overzicht van het hele document en het doel ervan

Projectoverzicht:

Een algemene beschrijving en functionaliteit van de software

Ontwerpoverwegingen:

Maak een lijst van de wegversperringen die moeten worden aangepakt voordat de software wordt gemaakt. Hieronder vallen details als:

• Eventuele verkeerde aannames of afhankelijkheden
• Algemene beperkingen die het ontwerp van de software kunnen beïnvloeden
• Doelen en richtlijnen voor het ontwerp van de software
• Ontwikkelingsmethodologie die zal worden gebruikt

Architectonische strategieën:

De strategieën die gebruikt zullen worden, zullen het systeem beïnvloeden.

Systeemarchitectuur:

Een overzicht op hoog niveau van hoe de functionaliteit en verantwoordelijkheden van het systeem zijn gepartitioneerd en toegewezen aan subsystemen of componenten.

Beleid en tactiek:

Ontwerp beleid en tactieken die geen brede architectonische implicaties hebben, d.w.z. dat ze geen significante invloed hebben op de algemene organisatie van het systeem en de structuren op hoog niveau.

Gedetailleerd systeemontwerp:

De meeste onderdelen die in het hoofdstuk Systeemarchitectuur worden beschreven, vereisen een meer gedetailleerde bespreking. Mogelijk moeten ook andere componenten en subcomponenten op een lager niveau worden beschreven.

Rollen en verantwoordelijkheden:

Informatie over deelnemers, waaronder een producteigenaar, teamleden en belanghebbenden, met duidelijk afgebakende verantwoordelijkheden en de geplande releasedoelen voor elk van de teamleden.

Veronderstellingen:

Lijst van technische of zakelijke veronderstellingen die het team zou kunnen hebben.

Architectuur en ontwerpprincipes:

Beschrijft de architectuur en ontwerpprincipes waarmee je het product ontwikkelt.

Schematische weergave van de software/het product:

Diagrammen die helpen bij het begrijpen en communiceren van de structuur en ontwerpprincipes.

Broncodedocument (optioneel):

Een broncodedocument is een technisch gedeelte dat uitlegt hoe de code werkt.

Broncodedocumenten kunnen details bevatten zoals:

• HTML-generatieraamwerk en andere toegepaste raamwerken
• Type gegevensbinding
• Ontwerppatroon met voorbeelden
• Veiligheidsmaatregelen
• Andere patronen en principes

Kwaliteitsborging:

De meest voorkomende zijn:

• Teststrategie
• Testplan
• Specificaties van testcases
• Checklists testen

Woordenlijst:

Een uitgebreide lijst van gedefinieerde termen en concepten die in het document worden gebruikt.

Soorten documentatie voor softwareontwerp

Het belangrijkste doel van dergelijke documentatie is om ervoor te zorgen dat alle betrokken belanghebbenden een gemeenschappelijk doel hebben en op één lijn zitten wat betreft een bepaald pad. Er zijn verschillende soorten documentatie voor softwareontwerp die dit doel dienen.

Productdocumentatie – Beschrijft het product dat wordt ontwikkeld en geeft instructies om er verschillende taken mee uit te voeren. Er zijn twee soorten productdocumentatie:

• Systeemdocumentatie – Verwijst naar documenten die het systeem en zijn onderdelen beschrijven. Het bevat documenten met vereisten, ontwerpbeslissingen, architectuurbeschrijvingen, programmabroncode en helpgidsen.
• Gebruikersdocumentatie – Verwijst naar handleidingen die voornamelijk zijn opgesteld voor eindgebruikers van het product en systeembeheerders. Gebruikersdocumentatie omvat tutorials, gebruikershandleidingen, handleidingen voor het oplossen van problemen, installatie- en referentiehandleidingen.

Procesdocumentatie – Omvat alle procesgerelateerde documenten die zijn gemaakt tijdens de ontwikkeling en het onderhoud van software. Bijvoorbeeld projectplannen, testschema’s, rapporten, standaarden, notities van vergaderingen, uitgewisselde e-mails, etc. Terwijl productdocumentatie het product beschrijft dat wordt ontwikkeld, legt procesdocumentatie het ontwikkelingsproces vast.

Systeemdocumentatie – Geeft alle belanghebbenden een overzicht van het systeem en de onderliggende technologie. Een systeemdocument bevat meestal ontwikkelingseisen, architectuurontwerp, broncode, validatiedocumenten, verificatie en testen, en een helpgids voor gebruikers. Soms bevat het ook details over wat een systeem moet doen, use cases, enz.

Het helpt altijd om te documenteren

Elk softwareontwikkelingsteam moet zich richten op het leveren van waarde aan zijn klanten en documentatie van hoge kwaliteit is net zo noodzakelijk als het softwareproduct dat wordt gemaakt. Goede softwaredocumentatie moet worden gevolgd als hygiëne en moet worden verstrekt, of het nu een specificatiedocument is voor ontwikkelaars en testers of softwarehandleidingen voor eindgebruikers. Uitgebreide softwaredocumentatie is specifiek, beknopt en relevant en moet beperkt blijven tot wat direct helpt om de projectdoelstellingen te bereiken.