Joel on Software

Joel on Software   Joel over Software

 

Andere "Joel on Software" artikelen in het Nederlands

Andere "Joel on Software" artikels in het Engels

Email de auteur (uitsluitend in het Engels)

 

Pijnloze Functionele Specificaties - Deel 4: Tips


Door Joel Spolsky
Vertaald door Mark Tetrode
15 october 2000

OK, we hebben het gehad over  waarop je specs nodig hebt, wat een spec inhoudt, and wie ze moet schrijven. In die vierde en laatste deel van deze serie geef ik je enkele adviezen om goede specs te schrijven.

De grootste klachten die je hoort van teams die wel functionele specificaties schrijven is "dat niemand die leest." Als niemand de specs leest worden de mensen die ze schrijven een beetje cynisch. Zoals die oude Dilbert cartoon waar medewerkers 10 centimeter dikke specs gebruiken om hun buro's uit te bouwen. Bij zo'n typische grote bureaucratische firma spendeert iedereen maanden en maanden om van die vervelende specs te schrijven. Eens de spec klaar is, wordt deze in de kast opgeborgen, om nooit meer te bekijken, en het produkt wordt van scratch geïmplementeerd zonder naar de spec te kijken, omdat niemand die leest, want dat is zo'n stoffige boel. Het proces om de spec te schrijven was wellicht een goede oefening, omdat iedereen dan op z'n minst moet nadenken over de issues. Maar het feit dat de spec in de kast werkt opgeborgen (ongelezen en ongeliefd) toen die klaar was, doet de mensen denken dat het een werk voor niets was.

Als de spec nooit gelezen wordt krijg je ook nog vaak ruzie wanneer het produkt wordt afgeleverd. Iemand (management, marketing of een klant) zegt: "wacht eens even! Je had me beloofd dat er een mossel koker in zou zitten! Waar is die mossel koker?" En de programmeurs zeggen dat "nee hoor, kijk maar in de spec, hoofdstuk 3, deel 4, paragraaf 2.3.0.1, daar zie je expliciet staan 'geen mossel koker'". Maar daar wordt de klant niet blijer van, en klanten hebben altijd gelijk, dus de knorrende programmeur moet een mossel koker in het programma proberen in te passen (wat hem nog cynischer maakt over specs). Of een manager zegt "hé, al die tekst in de dialogen is te uitgebreid, en er moet een advertentie bovenaan in de dialoog." En de gefrustreerde programmeurs zeggen "maar jij hebt die spec goedgekeurd met precies die layout en tekst van elke dialoog!" Maar natuurlijk, de manager had de spec niet echt gelezen, toen hij het probeerde liep zijn herseninhoud langzaam uit z'n oren, en, o ja, toen had-ie net z'n wekelijkse golfpartij.

Dus. Specs zijn goed, maar wat als niemand ze leest? As de spec-schrijver moet je trucks uithalen om de mensen je specte laten lezen, en je moet warschijnlijk ook proberen om een reeds te klein brein niet uit de oren te laten lopen.

De truck om mensen je schrijfsels te laten lezen is gewoonlijk een zaak van een goede schrijfstijl. Maar het is niet fair van me om te zeggen "wees gewoon een goede schrijver", en het daarbij te laten. Hier zijn vier eenvoudige regels die je absoluut moet volgen om specs te maken die gelezen worden.

Regel 1: Wees grappig

Inderdaad, regel nummer één om mensen je spec te laten lezen is om hun ervaring aangenaam te maken. Vertel me nu niet dat jij niet grappig kan zijn. Dat geloof ik niet. Eenieder heeft altijd wel grappige ideeën, je censureert die omdat ze denken dat het "onprofessioneel" zou zijn. Nou moe. Soms moet je die wet maar eens breken.

Als je het volume rotzooi leest dat ik geschreven heb op deze web site zal je zien dat er een paar stomme pogingen zijn om grappig zijn in elke tekst. Vier paragrafen terug maakte ik een vettige grap over hersenen en over managers die golf spelen. Eigenlijk ben ik niet zo grappig. Ik doe m'n best, en zelfs mijn proberen grappig te zijn is weer grappig, op zo'n droevige clown soort. Wanneer je een spec schrijft, is het gemakkelijk om grappig te zijn in de voorbeelden. Telkens wanneer je een voorbeeld moet geven hoe een feature werkt, in plaat van te schrijven:

  • De gebruiker tikt Ctrl+N om een nieuwe Medewerker tabel aan te maken en kan dan de namen van nieuwe medewerkers invoeren.

schrijf dan zoiets als:

  • Miss Piggy, die met haar lipstick om het toetsenbord rammelt omdat haar worstenvingertjes te vet zijn om te tikken, drukt om Ctrl+N om een nieuwe Vriendjes tabel te maken, en tikt als enige rij in "Kermit."

Als je veel Dave Barry leest, ontdek je dat één van de makkelijkste manieren om grappig te zijn is om specifiek te zijn als er niet om gevraagd wordt. "Scrappy pugs" is grappiger dan "honden". "Miss Piggy" is grappiger dan "de gebruiker". In plaats van te schrijven "speciale interesses" schrijf "linkshandige avocado-boeren". In plaats van de zeggen "Mensen die de uitwerpselen van hun hond niet opruimen moeten gestraft worden", zeg je dat ze "naar een gevangenis moeten worden gestuurd waar ze zo aleen zijn dat de de spinnen moeten betalen voor sex".

O ja, overigens, als je denkt dat het niet professioneel is om grappig te zijn, dan heb je gewoon geen gevoel voor humor. (Ontken het maar niet. Mensen zonder gevoel voor humor ontkennen zoiets altijd. Daar trap ik niet in.) En als je bij een firma werkt waar de mensen je minder waarderen omdat je specs fris en grappig aanvoelen, en gemakkelijk te lezen zijn, dan moet je maar een andere firma opzoeken. Het leven is veels te kort om je dagen door te brengen in zo'n sombere, miserabele plaats.

Regel 2: Een spec schrijven is zoals code schrijven voor  de hersenen

Waarom ik denk dat programmeurs moeite hebben om goede specs te schrijven?.

Als je code schrijft is je eerste publiek de compiler. Ja ik weet het, mensen moeten ook code lezen, maar over het algemeen is het wreed moeilijk voor hen. Voor de meeste programmeurs is het al moeilijk genoem om de code in een staat te krijgen zodat de compiler die leest en correct interpreteert, zorgen maken over de leesbaarheid voor anderen is een luxe-probleem. Als je nu schrijft:

void print_count( FILE* a, char  *  b, int c ){
    fprintf(a, "er zijn %d %s\n", c, b);}

main(){ int n; n =
10; print_count(stdout, "collega's", n) /* code deliberately obfuscated*/ }

of

printf("er zijn 10 collega's\n");

krijg je dezelfde uitvoer. Daarom, denk er eens over, krijg je programmeurs die dingen schrijven zoals:

Er bestaat een functie AdresVan(x) die gedefiniëerd is als de omvorming van een gebruiker x naar het RFC-822 formaat van het email adres van die gebruiker, een ANSI string. Als er nu twee gebruikers bestaan, gebruiker A en gebruiker B, en A wenst een email te sturen naar B. Dan initiëert gebruiker a een nieuw bericht gebruik makend van één van de (maar niet alle) technieken elders gedefiniëerd, en voert AdresVan(B) in het Aan: invoerveld.

Dit had moeten geschreven worden als:

Miss Piggy wil gaan lunchen, dus maakt ze een nieuwe email en tikt Kermit's adres in het Aan: veld. 

Technische notitie: hett adres moet een standaard internet adres zijn (moet de RFC-822 standaard volgen.)

Beiden "zeggen" hetzelfde, theoretisch, behalve dat de eerste zo cryptisch is dat je het vier keer moet lezen. Het tweede is veel gemakkelijker. Programmeurs proberen vaak specs te schrijven die op universitaire werken lijken. Zij denken dat een "correcte" spec ook "technisch" correct dient te zijn, en daar gaat het mis.

De fout is dat wanneer je een spec schrijft moet het niet alleen correct zijn, maar ook begrijpelijk, wat in programmeertermen betekend dat het zo geschreven moet worden dat het menselijk brien het moet kunnen "compileren". Eén van de grote verschillen tussen computers en de menselijke hersenen is dat computers eindelook kunnen wachten terwijl jij de termen definieert die je later wil gebruiken. Maar mensen begrijpen niet waar je het over hebt tenzij je ze eerst motiveert. Mensen willen niet eerst iets moeten decoderen, ze willen het gewoon in de goede volgorde lezen en begrijpen. Mensen moeten eerst het grote geheel zien, en dan kunnen de details worden ingevuld. Bij computer programma's begin je aan het begin, en werk je tot aan het einde, met detail overal. Een computer geeft er niet om als de variabele namen nietszeggend zijn. Een menselijk brein kan dingen beter begrijpen als je een levendig beeld kan scheppen door een verhaaltje te vertellen, of slechts een deel van een verhaal, immers, onze hersenen zijn ontwikkeld om verhalen te begrijpen.

Als je een schaakbord in het midden van een echt schaakspel toont aan een ervaren schaker voor enkele seconden, zal deze onmiddelijk zich het beeld inprenten van de plaats van elk stuk. Maar als je een aantal stukken verplaatst op een onlogische manier die normaal gezien niet kan gebeuren bij het schaken (bijvoorbeeld, pionnen op de eerste rij, of beide zwarte lopers op zwart), wordt het heel veel moeilijker voor hen om zich het bord in te prenten. Dit is verschillend van de manier zoals computers denken. Een computer programma dat een schaakbord kan onthouden kan even makkelijk een 'mogelijk' als een 'onmogelijk' schaakbord onthouden. Het menselijk brein werkt niet als random access; sommige wegen zijn sterker in ons brein en sommige dingen zijn gewoon gemakkerlijker te begrijpen dan andere, omdat ze vaker voorkomen.

Dus, wanneer je een spec schrijft, beeld je dan de persoon in voor wie je het schrijft, en probeer je te bedenken wat je van hen vergt bij elke step. Vraak jezelf af  bij elke zin of de persoon die dit gaat lezen het ten volle zal begrijpen, in de context van wat je hem al verteld hebt. Als sommige mensen uit je doelgroep niet weten wat RFC-822 is moet je het definiëren, of op z'n minst de verwijzing naar RFC-822 verbergen in een technische notitie, zo dat de executive-types die de spec lezen niet opgeven en stoppen met lezen bij de eerste de beste technische term die ze tegen komen.

 

Regel 3: Schrijf zo simpel als mogelijk

Gebruik geen gestileerde, formele taal omdat je denkt dat het onprofessioneel is om eenvoudige zinnen te gebruiken. Gebruik de meest eenvoudige taal die maar mogelijk is. 

Mensen gebruiken woorden zoals "invoeren" omdat ze denken dat "tikken" onprofesioneel overkomt. (Alweer dat woord "onprofessioneel". Elke keer dat iemand je vertelt dat je iets niet zou moeten doen omdat het "onprofessioneel" is weet je dat ze geen echte argumenten meer hebben.) Ik denk dat veel mensen denken dat duidelijk schrijven betekent dat er iets mis is.

Splits de dingen op in korte zinnen. Als je moeite hebt om iets duidelijk op te schrijven, breek die zin dan op in twee of drie kortere zinnen. 

Vermijd lappen tekst: volledige pagina's met enkel tekst. Mensen worden daardoor afgeschrikt en zullen het niet lezen. Wanneer heb je voor het laatst een blad of krant gezien met een volledige pagina met enkel tekst? Week- en maandbladen gaan zelfs zo ver dat ze een zin uit het artikel nemen en afdrukken in het midden van de pagina, in een groot lettertype, enkel om het beeld van een pagina vol met tekst te voorkomen. Gebruik genummerde lijsten, of lijsten met putjes, grafieken, tabellen en voldoende witruimte zodat het lezen gemakkelijker gemaakt wordt.

             

 

"Week- en  maandbladen gaan zelfs zo ver dat ze een zin uit het artikel nemen en afdrukken in het midden van de pagina, in een groot lettertype, enkel om het beeld van een pagina vol met tekst te voorkomen"


 

 

Niets maakt een spec beter dan vele schermadrukken. Eén plaatje vertegenwoordigt duiden woorden. Eenieder die specs voor Windows software schrijft moet op z'n minst Visual Basic installeren, en op z'n minst zo leren te gebruiken dat-ie mooie voorbeeldschermen kan maken. (Voor de Mac gebruik je best REAL Basic; voor web pagina's Front Page of Dreamweaver). Dan maak je een schermafdruk (Ctrl+PrtSc) en plak je die in je spec.

Regel 4: Herzie en herlees meerdere keren

Eh, goed, if was eigenlijk van plan om lang uit te wijden over deze regel, maar die is eigenlijk te simpel en duidelijk. Herzie en herlees je eigen spec meermaals, goed? Als je een zin tegenkomt die niet super gemakkelijk te begrijpen is, herschijf die dan.

Nu ik zoveel tijd bespaard heb door Regel 4 niet uit te leggen, komt nu ....

Regel 5: Sjablonen? Niet doen!

Vecht tegen de verleiding om sjabolen te gebruiken voor specs. Eerst denk je wellicht dat het belangrijk is dat "elke spec er het zelfde uit ziet". Hint: dat is niet belangrijk. Welk verschil maakt het? Ziet elk boek op jouw boekenplank er het zelfde uit? Zou je dat willen?

Meer nog, als je sjablonen gebruikt, gaat het volgende gebeuren. Je voegt een aantal secties toe aan het sjablooon voor dingen die jij belangrijk vindt voor elke feature. Voorbeeld: Belangrijke Bill vaardigt uit dat vanaf nu elk Microsquish produkt een "Internet Component" moet hebben. Wanneer iemand nu een spec schrijft, ongeacht hoe triviaal, moeten ze die sectie "Internet Component" invullen, zelfs als ze enkel de spec maken voor het Microsquish Toetsenbord. (En jij vroeg je al af waarom al die waardeloze Internet shopping toetsen op elk toetsenbord als paddenstoelen uit de grond rijzen).

Als al deze sectie bij elkaar worden gevoegd zal het sjabloon aardig groot worden. (Hier is een voorbeeld van een ongelofelijk slecht sjabloon voor specificaties. Wie heeft nu in hemels naam nood aan een bibliografie in een spec. Of een verklarende woordenlijst?) De moeilijkheid met zo'n grote sjabloon is dat mensen bang worden om nog een spec te schrijven omdat het zo'n vervelende taak lijkt.

Een spec is een document waarvan jij wil dat mensen het lezen. In die optiek is het niet verschillend van een artikel uit Vrij Nederland of De Humo of een scriptie? Heb je ooit gehoord van een professor die studenten een sjabloon gaf voor scripties? Heb je ooit twee scripties gelezen die in een sjabloon zouden passen? Zeg het maar.



De originele versie van dit artikel verscheen in het Engels onder de naam Painless Functional Specifications Part 4  

Joel Spolsky is de oprichter van Fog Creek Software, een klein softwarebedrijf in New York. Hij studeerde af aan de Yale universiteit, en heeft als programmeur en manager gewerkt bij Microsoft, Viacom en Juno.


De inhoud van deze pagina's vertegenwoordigt de mening van één persoon.
Alle inhoud Copyright ©1999-2005 door Joel Spolsky. Alle rechten voorbehouden.

FogBUGZ | CityDesk | Fog Creek Software | Joel Spolsky