Front-end documentatie » Robert Jan Verkade

Tijdschrift voor webwerkers » Artikel #126

Iets saaiers dan het documenteren van je beslissingen is nauwelijks denkbaar. En toch gaan we er mee aan de slag. Documenteren is namelijk handig en nuttig, en als je dat bedenkt wordt het zelfs bijna leuk om te doen. En als ik je hiermee nog niet overtuig om het artikel te lezen, dan vertel ik je vast dat er aan het eind een cadeautje voor je klaar staat.

Documentatie is een investering die je in een later stadium gemakkelijk terug gaat verdienen. Zodra je documenteert wat je doet (en waarom!) is het voor iedere ontwikkelaar duidelijk aan welke standaarden de site voldoet en zal moeten blijven voldoen. De opdrachtgever krijgt een document in handen waarmee de kwaliteit van de site bewaakt kan worden, en jij krijgt na verloop van tijd niet de tranen in je ogen van de rommel die de site geworden is. Als je je beslissingen documenteert dan kun je na verloop van tijd een project makkelijker opstarten, omdat je weet wat de afspraken waren. Dat scheelt dus een hoop tijd, en tijd is geld!

Ik ga je een aantal tips geven en je op weg helpen bij het opzetten van een stijlgids. Zo blijven je beslissingen voor het nageslacht bewaard.

Niet ieder project heeft overigens een uitgebreide stijlgids nodig, maar elk project heeft wel duidelijkheid nodig. Pas je werkzaamheden aan op de schaalgrootte van het project en de verantwoordelijkheid die je in het project draagt: te veel documenteren is niet goed (dan schiet je met een kanon op een mug). Het is heel simpel: documenteren is communiceren. Met je gezond verstand kom je al een heel eind.

Aantekeningen in je markup

Je krijgt waarschijnlijk steeds vaker te maken met een redesign van een bestaande site in plaats van dat je volkomen blanco kunt beginnen aan een project. Op zo’n moment mag je hopen dat het front-end door kundige mensen is opgezet (anders kun je beter opnieuw beginnen), zodat je snel de markup kunt doorgronden. Een simpele methode om deze tijd zo kort mogelijk te maken is kleine aantekeningen te maken in je documenten. Als je er te veel in zet dan werkt het trouwens ook weer contra-productief: wees spaarzaam met je opmerkingen en signaleer alleen de belangrijke punten die je beslissingen bij het maken van de pagina’s toelichten.

De meeste tijd gaat vaak zitten in het naspeuren hoe de HTML is opgebouwd. Dan is het wel zo prettig om te weten waar de afsluitende div-tags bij horen. Laten we er maar eens een voorbeeld bij pakken.

<body>
 <div id="kader">
  <div id="kop">
   <div id="functies">
    ...
   </div>
   <div id="menu">

    ...
   </div>
   <div id="kruimelpad">
    ...
   </div>
  </div>
  <div id="content">

   <div id="kern">
    ...
   </div>
   <div id="extra">
    <div id="nieuws">
     ...
    </div>

    <div id="column">
     ...
    </div>
   </div>
   <div id="voettekst"> 
    ...
   </div>
  </div>

 </div>
</body>

De naamgeving van de verschillende id en class attributen is behoorlijk duidelijk. En toch is het altijd even zoeken wat bij elkaar hoort. En als je content moet invoegen wil je natuurlijk wel precies weten waar je dat kunt doen (en waar niet!). Door een comment toe te voegen waarin je aangeeft welke div er wordt afgesloten ontstaat de gewenste duidelijkheid. En voor degene die het in een CMS moet knippen is het nu een peulenschil om de verschillende blokken te definiëren.

<body>
 <div id="kader">
  <div id="kop">
   <div id="functies">
    ...
   </div> <!-- #functies -->

   <div id="menu">
    ...
   </div>  <!-- #menu -->   
   <div id="kruimelpad">
    ...
   </div> <!-- #kruimelpad -->

  </div> <!-- #kop -->
  <div id="content">
   <div id="kern">
    ...
   </div> <!-- #kern -->

   <div id="extra">
    <div id="nieuws">
     ...
    </div> <!-- #nieuws -->
    <div id="column">
     ...
    </div> <!-- #colomn -->

   </div> <!-- #extra -->
   <div id="voettekst"> 
    ...
   </div> <!-- #voettekst -->
  </div> <!-- #content --> 
 </div> <!-- #kader -->      

</body>

We kijken allemaal wel eens in de broncode van een site: de broncode is openbaar en voor iedereen toegankelijk. Daarom is dit dus niet de plaats om je schrijftalent te ontwikkelen, een vete met je collega uit te vechten of olijke ascii-art te publiceren. Een comment zou geen woord te veel (of te weinig) moeten bevatten — het gaat er om dat je commentaren praktisch, duidelijk en nuttig voor je eventuele opvolgers zijn.

Versiebeheer en contact-informatie

Als er meerdere bedrijven betrokken zijn bij de ontwikkeling van een website kunnen vragen rijzen bij de implementatie. Dan is het handig als de andere partij zich niet het hoofd hoeft te breken over wie er aan het front-end heeft gewerkt. Misschien zal er na uitleveren van je templates een foutje — meestal in de CSS — aan het licht komen, waardoor je een nieuwe versie aan zult leveren. Je CSS-bestand is de aangewezen plaats om hier een vermelding over neer te zetten. Je CSS zal immers nóg wel eens aangepast kunnen worden. Ook hier hou je het kort en bondig, bijvoorbeeld:

/* print-stylesheet: www.voorbeeld.nl */
/* versie 1.0 - 30/05/2006 - robertjan@voorbeeld.nl */

Overzicht in je stylesheet

Een CSS-bestand beslaat al snel meer dan 500 regels, en kan oplopen tot een veelvoud hiervan. Voor je eigen overzicht — maar ook voor de specificity — is het een goede zet om om je bestand goed te organiseren en vervolgens aan te tekenen wat waar bij hoort. Een overzichtelijk bestand bespaart je echt een hoop tijd. Lees er meer over in: CSS Organization Tip 1: Flags.

Overzicht in je JavaScript

Wat voor het CSS-bestand geldt, geldt ook voor je JavaScript. Geef aan welk code-fragment bij welke functie hoort. Niks is zo vervelend als er naar moeten zoeken in een onoverzichtelijk bestand. Overweeg ook — als je te maken hebt met veel code — je JavaScript op te splitsen in meerdere .js-bestanden. Zo kun je functionaliteiten groeperen en het overzicht bewaren. JavaScript-goeroe Jeremy Keith maakt hier gretig gebruik van.

Een stijlgids

Ontwerpers zijn er al lang aan gewend om hun beslissingen te documenteren in een stijlgids. Voor de meeste ontwikkelaars is dit (nog) een flinke stap. Toch kan het absoluut geen kwaad om een beknopte stijlgids bij je templates aan te leveren. Al was het maar voor jezelf, want na een paar jaar wil je nog wel terug kunnen vinden wat je beslissingen toen waren.

Door een aantal zaken (die je natuurlijk in het offertetraject al met je opdrachtgever had besproken) vast te leggen is het voor altijd duidelijk wat er is uitgeleverd. En voor een opdrachtgever is het beslist de moeite waard om de kleine investering in zo’n document te doen. Ze betaalt immers een aardig bedrag voor een project, dan wil ze ook iets in handen krijgen waarmee de kwaliteit gewaarborgd wordt.

Wat staat er in?

Je kunt de stijlgids zo ver uitbreiden als het budget toelaat. Als je zelf nog nooit een stijlgids hebt gemaakt dan is het wellicht een flinke stap om er aan te beginnen. Dan kan het handig zijn om te starten aan de hand van een voorbeeld.

En omdat Naar Voren nu vier jaar bestaat trakteren we je op een opzet van een front-end stijlgids. De basis krijg je van ons cadeau. Je kunt deze basis aanpassen aan de eisen van je eigen project.

Op hoofdlijnen zou een front-end-stijlgids de onderstaande onderwerpen kunnen bevatten:

Algemene informatie
- Validatie
- DOCTYPE declaratie
- Karakterset
- Taal
- Toegankelijkheid
- Browserondersteuning
(X)HMTL
- Betekenisvolle markup
- Het gebruik van tabellen
- Afkortingen
- Taalvariaties
CSS
- CSS management
- Declaraties, id’s en classes
- Typogrammen
- Kleurgebruik
Javascript
- Modern JavaScript
- Openen van nieuwe vensters
- Externe links
Contactgegevens

Cadeau

Je kunt het uitgewerkte voorbeeld van de stijlgids bekijken, maar je kunt ook de “kale” versie downloaden (zip - 28kB). De kale versie bevat alle content, maar nauwelijks opmaak. Je kunt ’m naar eigen smaak vormgeven. En als je ’m anders wilt opzetten en/of een voorkeur hebt voor een Engelstalig document, dan is het voorbeeld van Andy Budd een prettige start. Die stijlgids hoort bij het boek CSS Mastery en wordt aangeboden in de zip met voorbeeld-bestanden. Download “the book examples” (zip - 694kB) , pak ’m uit en volg het pad: Source Code » Chapter01 » Styleguide.

Tenslotte

Niet ieder project heeft een uitgebreide stijlgids nodig, en niet in ieder project hoef je vanalles te documenteren. Maar als je er niet aan begint omdat je denkt dat het veel tijd kost, dan zit je er naast. Het is relatief kleine investering in tijd die je ruimschoots terugverdient doordat je iets vaker nadenkt over wat je precies doet, en daar word je een betere webwerker van. En betere webwerkers werken niet alleen beter, ze werken ook sneller!

Robert Jan Verkade

startte meer (iets) meer dan vier geleden Naar Voren omdat het werken aan het web op een dramatisch dieptepunt zat. Bij de pakken neerzitten en meedoen aan de “het wordt toch nooit meer iets” gedachte was geen optie. Een belangeloos tijdschrift voor webwerkers startten wel. Gelukkig maakt hij de site niet alleen, een geweldige redactie staat steeds paraat. Robert Jan verdient nog steeds zijn brood met eend en houdt zich bezig met alles waarmee een sitebezoeker in aanraking komt. Verder heeft hij nog steeds geen leuke hobbies.

Publicatiedatum: 14 juni 2006

Naar Voren is op 18 juli 2010 gestopt met publiceren. De artikelen staan als een soort archief online. Het kan dus zijn dat de informatie verouderd is en dat er inmiddels veel betere of makkelijkere manieren zijn om je doel te bereiken.