CleanText: De technische schrijfgids voor ICT-studenten
Download hier > 'CleanText: De technische schrijfgids voor ICT-studenten'
Gebrek aan bruikbare softwaredocumentatie kan leiden tot verkeerde handelingen, verstoorde processen en haperende dienstverlening bij softwareleveranciers.
Voorbeelden
Een klant van een softwareleverancier wil nieuwe functionaliteiten laten toevoegen aan een bestaande applicatie. De oorspronkelijke developers werken niet meer bij deze leverancier en hebben bovendien geen bruikbare documentatie achtergelaten. Hierdoor kunnen de nieuwe developers de applicatie niet eenvoudig aanpassen. Ze zijn gedwongen om de applicatie geheel opnieuw te ontwikkelen. Het project duurt langer, de kosten stijgen en de klant verliest het vertrouwen in de softwareleverancier.
Bij een telecom operator verwijdert een engineer de configuratie van een interconnectiepunt tijdens het updaten van software. Oorzaak? Verkeerde handelingen door inconsistente softwaredocumentatie. Diverse bedrijven en instellingen worden onbereikbaar en kunnen hun dienstverlening circa acht uur niet voortzetten.
Waarom dit boek?
Technische documentatie fungeert als een cruciale kennisbron voor het waarborgen van de kwaliteit en de continuïteit van software. Het maken en onderhouden van deze documentatie is een taak voor ICT’ers, aangezien zij over vakkennis beschikken en direct betrokken zijn bij het ontwikkelproces.
Er zijn diverse Nederlandstalige boeken over de stijl en structuur van teksten. Deze boeken zijn voor een breed doel geschreven. Ze zijn niet gericht op schrijftaken in de ICT zoals requirements specificeren, ontwerp beschrijven, pseudocode schrijven, code voorzien van commentaar, testgevallen formuleren en application programming interface (API) documenteren.
CleanText is speciaal geschreven voor ICT-studenten zodat ze in hun opleidingstraject leren om doeltreffend en kosteneffectief te schrijven. Het boek richt zich op zes fundamentele vaardigheden voor het construeren van technische teksten:
- CleanText kwaliteitskenmerken toepassen
- Schrijftaken scherp analyseren
- Teksten logisch structureren
- Zinnen doeltreffend formuleren
- Woorden effectief gebruiken
- CleanText kwaliteitscontrole uitvoeren.
De belangrijkste bouwstenen van de hoofdstukken zijn praktische concepten, voorbeelden en oefeningen met uitwerkingen. Alle concepten, voorbeelden en oefeningen zijn gerelateerd aan de levenscyclus van software. Deze eigenschappen zorgen ervoor dat studenten vakgericht leren documenteren. De verworven kennis is direct toepasbaar bij technische schrijftaken.
De auteurs
Dit boek is geschreven door Hossein Chamani, Anne van Brussel en Jos van Rooyen. De auteurs hebben geen financiële of commerciële belangen. Daarom is het boek gratis voor studenten en andere belanghebbenden.
Hossein Chamani heeft ervaring in functies en rollen als hogeschooldocent, trainer, projectmanager, testmanager, network integrator en network manager. Hij werkt als vakdocent bij de opleiding Informatica van Hogeschool Rotterdam. Daarnaast publiceert hij op het gebied van software testen en technische communicatie.
Anne van Brussel werkt als vakdocent usability testing bij de opleiding Informatica van Hogeschool Rotterdam. Ze heeft ervaring als trainer, internationaal gastdocent en hogeschooldocent. Anne heeft onderwijswetenschappen gestudeerd aan de Open Universiteit. Ze is gespecialiseerd in onderwijsontwerp, onderzoek, toetsing en het optimaliseren van docentschap en leerklimaat.
Jos van Rooyen is partner bij Identify. Hij werkt actief aan het ontwikkelen en invoeren van het vakgebied softwarekwaliteit en testen in het ICT-onderwijs. Jos heeft diverse publicaties op zijn naam staan en richt zich op het vernieuwen van zijn vakgebied. Naast zijn werk als consultant, kwaliteitsregisseur en publicist is hij een graag geziene spreker op diverse conferenties.
Dit boek is geschreven door Hossein Chamani, Anne van Brussel en Jos van Rooyen. De auteurs hebben geen financiële of commerciële belangen. Daarom is het boek gratis voor studenten en andere belanghebbenden.
Hossein Chamani heeft ervaring in functies en rollen als hogeschooldocent, trainer, projectmanager, testmanager, network integrator en network manager. Hij werkt als vakdocent bij de opleiding Informatica van Hogeschool Rotterdam. Daarnaast publiceert hij op het gebied van software testen en technische communicatie.
Anne van Brussel werkt als vakdocent usability testing bij de opleiding Informatica van Hogeschool Rotterdam. Ze heeft ervaring als trainer, internationaal gastdocent en hogeschooldocent. Anne heeft onderwijswetenschappen gestudeerd aan de Open Universiteit. Ze is gespecialiseerd in onderwijsontwerp, onderzoek, toetsing en het optimaliseren van docentschap en leerklimaat.
Jos van Rooyen is partner bij Identify. Hij werkt actief aan het ontwikkelen en invoeren van het vakgebied softwarekwaliteit en testen in het ICT-onderwijs. Jos heeft diverse publicaties op zijn naam staan en richt zich op het vernieuwen van zijn vakgebied. Naast zijn werk als consultant, kwaliteitsregisseur en publicist is hij een graag geziene spreker op diverse conferenties.
Aanbevelingen
“Technisch schrijven is een vak. Een leuk en noodzakelijk vak. Leuk, want een goed opgebouwde en scherp geformuleerde tekst geeft de schrijver de voldoening van vakmanschap. Noodzakelijk, want zonder goede informatie is ICT meestal niet te gebruiken en niet te onderhouden. Dit boek geeft praktische richtlijnen voor het technisch schrijven. De opdrachten nodigen uit om zelf met de stof aan de slag te gaan. Dat maakt het geschikt voor zelfstudie en voor gebruik in het technisch onderwijs – in de ICT en de techniek in het algemeen. Vanuit mijn werkervaring en onderwijservaring wil ik dit boek warm aanbevelen.”
> Peter van Bart, Algemeen directeur Eluxis bv, adviseur bij de masteropleiding Technology & Communication van Universiteit Twente, auteur van ‘Basisboek technische communicatie’
Documenteren is vaak niet de favoriete bezigheid van ICT’ers en ICT-studenten. Ze denken creatief en exact en zijn het liefste aan de slag met de ontwikkeling van innovatieve softwareproducten. Toch is documentatie heel belangrijk om samen aan projecten te kunnen werken en om software te kunnen blijven doorontwikkelen. Dit boek laat op een heel praktische en heldere manier zien hoe je goede documentatie opstelt. Zonder overbodige informatie, heel gestructureerd en praktisch, zoals informatici prettig vinden. Het boek CleanText is zeer geschikt voor zelfstudie vanwege de vakgerichte voorbeelden, oefeningen en opdrachten.
> Heleen Elferink, Directeur Instituut voor Communicatie, Media en Informatietechnologie bij Hogeschool Rotterdam‘Het schrijven van documentatie wordt vaak gezien als sluitpost in een softwareontwikkeltraject, echter is in veel gevallen de noodzaak wel aanwezig om documentatie op te stellen. Dit boek geeft ICT-studenten op een laagdrempelige manier inzicht hoe dit te doen voor verschillende fasen in de Software Development Life Cycle.
> Maurice van Haperen, Hogeschooldocent Informatica bij Avans Hogeschool
“In mijn werk als senior Software Engineer gebruik ik documentatie als informatiebasis om systemen te ontwikkelen voor opdrachtgevers. Helder en logisch geschreven teksten verhogen de effectiviteit en efficiëntie van het totale ontwikkelproces. Dit boek helpt iedere ICT-student en professional bij het schrijven van technische teksten.”
> Patrick Kik, Software Engineer en oud-student Hogeschool Rotterdam
"Het correct kunnen schrijven van technische documentatie is cruciaal op de werkvloer, zoals ik zelf al menigmaal heb ervaren. Aan de hand van heldere voorbeelden en praktische opdrachten leert dit boek je om efficiënte, volledige en juiste teksten te schrijven. Hier zal je als ICT-student nog lang profijt van hebben."
> Michelle Ritzema, Web Developer bij Robeco en oud-studente Hogeschool Rotterdam
“Logische, eenduidige en heldere teksten zoals requirements, acceptatiecriteria en testcases zijn onmisbaar voor het effectief testen van informatiesystemen. In dit praktische boek leer je in slechts enkele uren hoe je logisch, eenduidig en helder kunt schrijven. Het boek onderscheidt zich met handige voorbeelden en oefeningen uit het ICT-vakgebied.”
> Huib Schoots, Senior Agile & Test Consultant bij De Agile Testers
"Met dit praktische boek ontwikkel je een schrijfstijl die onmisbaar is voor het schrijven van eenduidige requirements in natuurlijke taal. Het boek is helder geschreven en bevat volop voorbeelden en oefeningen. De auteurs hebben je het hierdoor gemakkelijk gemaakt om met de 22 handreikingen aan de slag te gaan. "
> Nicole de Swart, Requirementsexpert en trainer bij Reaco Academy, auteur van Handboek Requirements en coauteur van Grip op Requirements
"Als docent software engineering zie ik veel studenten die grote moeite hebben met het schrijven van een goede tekst. Dat is niet verbazingwekkend: schrijven is moeilijk. Maar het is ook een noodzakelijke vaardigheid voor ontwikkelaars, in contact met klanten en collega's is een goede schriftelijke communicatie noodzakelijk.
Chamani, Van Brussel en Van Rooyen hebben een effectieve methode ontwikkeld die handige gereedschappen biedt om goede en bruikbare teksten te maken. Gebaseerd op een kwaliteitsmodel worden methoden beschreven om teksten te analyseren en te verbeteren maar ook om nieuwe teksten te schrijven.
Het boek is praktisch opgezet. Met een minimum aan theoretische beschouwingen en een maximum aan voorbeelden en oefeningen biedt het iedere student of ontwikkelaar de mogelijkheid met minder inspanning betere resultaten te bereiken. Een aanrader!"
> Huub van Thienen, Hoofddocent Software Engineering bij Hogeschool van Amsterdam
“Als ICT-student bouw en implementeer je technische systemen voor bedrijfskritische processen. Daarin werk je op vele manieren samen en moet er veel gecommuniceerd worden. Ook over en in de ICT-systemen die gebouwd en gebruikt worden. Een aanzienlijk deel van die communicatie is schriftelijk en specifiek voor de rol van ICT’ers. Denk aan documentatie van code en specificatie van requirements. Bij het opstellen daarvan is helder, logisch en eenduidig schrijven een onmisbare vaardigheid.
Dit boek beschrijft wat dat is en hoe je het voor elkaar kunt krijgen. Dat doet het op een gestructureerde manier die goed aansluit bij de systematiek van het ICT-vakgebied. Daardoor biedt het ICT’ers de mogelijkheid de juiste kennis en vaardigheden te verwerven voor het schrijven van technische teksten in de levenscyclus van software. Een vaardigheid die ongetwijfeld leidt tot betere communicatie, samenwerking en uiteindelijk betere ICT-systemen.”
> Frens Vonken, Voorzitter stichting HBO-I en Teamleider Fontys Hogeschool
