CleanText 2.1: De technische schrijfgids voor ICT’ers, coaches en trainers

 Download hier CleanText 2.1: De technische schrijfgids voor ICT’ers, coaches en trainers

Ben je als ICT’er in staat om relevante informatie over software scherp te analyseren en helder te documenteren voor jezelf en voor andere belanghebbenden van software? Gebrek aan bruikbare softwaredocumentatie kan leiden tot verkeerde handelingen, verstoorde processen en haperende dienstverlening.

Voorbeelden

• Een klant van een softwareleverancier wil nieuwe functies 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 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.

Doelgroep

CleanText is geschreven voor ICT’ers in opleiding. Een ICT’ers in opleiding kan:

• Een student zijn die een reguliere ICT-opleiding volgt. 
• Een trainee zijn die een bedrijf of instelling zelf opleidt voor een functie, rol of loopbaan in de ICT.

Het boek is ook bedoeld als inspiratiebron voor coaches en trainers die taalgericht vakonderwijs of vakgericht taalonderwijs willen ontwikkelen voor ICT’ers.

Doel

Als ICT’er leer je informatie over software scherp te analyseren en helder te documenteren. De informatie die je nodig hebt om het juiste softwareproduct op de juist manier te ontwikkelen en te testen in projecten.

Waarom dit boek?

Softwaredocumentatie is cruciaal voor het waarborgen van de kwaliteit en de continuïteit van software. Als ICT’er ben je vaak zowel de maker als de gebruiker van deze documentatie omdat je direct betrokken bent in alle fases van het ontwikkelproces.

Er zijn diverse Nederlandstalige boeken en online cursussen over de stijl en structuur van teksten. Deze boeken en cursussen zijn voor een brede doelgroep geschreven. Ze zijn niet gericht op de taken van ICT’ers.

CleanText is vakspecifiek. Alle leerdoelen en leeractiviteiten zijn gekoppeld aan de taken van ICT’ers. Als ICT’er kun je de verworven kennis en vaardigheden direct toepassen in praktijk en je deskundigheid verder ontwikkelen.

Opbouw

Dit boek bestaat uit twee delen. Elk deel en elk hoofdstuk kun je onafhankelijk van elkaar bestuderen of gebruiken als naslagwerk. Het boek bevat ook een project.

Deel 1

Deel 1 bevat zes hoofdstukken. Deze richten zich op analytische schrijfvaardigheden voor software ontwikkelen en testen. Daarom is het aanbevolen om deel 1 te gebruiken naast je eerste cursus over programmeren of software testen.

    01. Requirements schrijven
    02. Risk cases specificeren

    03. Acceptatiecriteria schrijven

    04. Functionele decomposities opstellen
    05. Condities en acties formuleren
    06. Testgevallen en test charters schrijven.

Deel 2

Deel 2 bevat vijf hoofdstukken. In dit deel leer je hoofdzakelijk helder, coherent en consistent te documenteren voor de belanghebbenden van software.

    07. Schrijftaken scherp analyseren

    08. Teksten logisch structureren

    09. Zinnen doeltreffend formuleren
    10. Woorden effectief gebruiken
    11. Kwaliteitscontrole uitvoeren.

Innovatieproject

Het innovatieproject is een optioneel deel van CleanText 2.0. In het project ontwikkel je een Proof of Concept voor een innovatief product. Tegelijkertijd pas je de verworven schrijfvaardigheden op een pragmatische manier toe. De Proof of Concept kun je ontwikkelen in een programmeertaal die wilt leren of al beheerst. In elk hoofdstuk van dit boek vind je een schrijfopdracht die gerelateerd is aan het Innovatieproject. Deze opdrachten zijn ook optioneel. Je voert deze alleen uit als ze relevant zijn voor je project.

Verschillen en overeenkomsten met de eerste druk van CleanText

De eerste druk van CleanText bestond uit zes hoofdstukken. CleanText 2.0 bestaat uit elf hoofdstukken. Hoofdstuk 1 t/m 6 zijn nieuw. Dit geldt ook voor het Innovatieproject en de bijlagen. Hoofdstuk 7 t/m 11 zijn de revisies van hoofdstuk 1 t/m 6 van de eerste druk.

De auteur

Hossein Chamani heeft ervaring in functies en rollen als docent, trainer, projectmanager, testmanager, network integrator en network manager. Sinds 2001 werkt hij als vakdocent bij de opleiding Informatica van Hogeschool Rotterdam. Hij publiceert op het gebied van software testen en technische communicatie in de ICT.

Hij is één van de vier auteurs van het boek ‘Aan de slag met software testen’. Daarnaast is hij de oprichter van en auteur bij CleanText Academy.

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 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 bij het ministerie van BZK

"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

“Logische, eenduidige en heldere teksten zoals requirements, acceptatiecriteria en testgevallen zijn onmisbaar voor het effectief testen van informatiesystemen. In dit praktische boek leer je hoe je logisch, eenduidig en helder kunt schrijven. Het boek

onderscheidt zich met handige voorbeelden en opdrachten 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 opdrachten. De auteur heeft je het hierdoor gemakkelijk gemaakt om met de drieëntwintig 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.

De auteur heeft 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 opdrachten 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, Managing Director bij Fontys Hogeschool ICT