Stijlgids voor het schrijven documentatie

Deze stijlgids geeft richtlijnen voor het schrijven van documentatie op de website van de Nederlandstalige Drupalgemeenschap (drupal.be / drupal.nl).

Deze stijlgids is nadrukkelijk in aanbouw, want naarmate we meer schrijven, zullen er meer richtlijnen nodig zijn.

Deze stijlgids volgt zo veel mogelijk de Engelstalige stijlgids van Drupal. Daarin wordt de ideale schrijfstijl voor Drupaldocumentatie als volgt gekarakteriseerd: "makkelijk, duidelijk, beknopt, aantrekkelijk, levendig, eerlijk, grappig (waar toepasselijk), respectvol en toegankelijk". Ga er maar aanstaan.

Voor richtlijnen wat betreft Nederlandse taal en spelling volgt deze gids zo veel mogelijk de adviezen van het het Groene boekje en de website Taaladvies van de Nederlandse Taalunie.

Drupal

Je schrijft Drupal met een hoofdletter.

Drupal

Samenstellingen

In tegenstelling tot het Engels moeten samenstellingen in het Nederlands aan elkaar geschreven worden.

Niet: systeem beheerder, installatie bestand
Wel: systeembeheerder, installatiebestand

Samenstellingen met eigennamen

Je schrijft samenstellingen met eigennamen aan elkaar.

Drupalgemeenschap, Drupalwesbite, Drupalinstallatie, Drupalconorganisatie, Excelbestand, Powerpointpresentatie, Linuxmachine

Samenstellingen met afkortingen

Je schrijft samenstellingen met afkortingen met een koppelstreepje.

PHP-script, CSS-bestand, CCK-veld

Woorden uit het Engels

Veel Drupalterminologie is in het Engels. Voor veel woorden zijn makkelijk Nederlandse equivalenten te vinden. Andere woorden verliezen juist hun betekenis als je ze vertaalt. Waar geen vertaling mogelijk is gebruiken we de Engelse termen. Speciale markeringen zijn niet nodig. Engelse zelfstandige naamwoorden schrijf je met kleine letter. Samenstellingen schrijf je aan elkaar.

e-mail, internet, online, harddisk

Niet: system settings, error message, community, account details
Wel: systeeminstellingen, foutmelding, gemeenschap, accountgegevens

Niet: de Drupalkern, sjabloon, open broncodeproject, lidmaatschap
Wel: de core, template, open source project, account

Drupalversie

Vermeld in de documentatie altijd de hoofdversie van Drupal. Indien nodig vermeld de exacte versie.

Drupal 5, Drupal 6, Drupal 7, Drupal 6.12

Links (vorm)

Gebruik een beknopte maar duidelijke tekst voor je links.

Wel: Leer hoe je een Drupalsite opzet met xampp

Een Drupalsite opzetten met xampp
Drupal met xampp

Niet: xampp
Zie de tutorial op drupal.org over het opzetten van een Drupalsite met xamp

Waarschuw gebruikers als je link naar iets anders leidt dan een normale webpagina:
Leer hoe je een Drupalsite opzet met xampp (PDF 38MB)

Gebruik relative links waar mogelijk
Niet: <a href="http://www.drupal.be/node/1234567">
Wel: <a href="/node/1234567">

Plaats links in de normale lopende tekst:
Niet: Ik hou van van kattenstaarten. Lees er meer over door <a href="http://www.catstailsrule.com">hier te klikken</a>
Wel: Mijn favorite lichaamsdeel van een kat is de <a href="http://www.catstailsrule.com" title="Informatie over katten en hun staarten">staart</a>

Gebruik www.example.com als domeinnaam in voorbeeldlinks.

Links (verwijzing)

We verwijzen in de documentatie alleen naar drupal.org, api.drupal.org en drupal.be. Niet naar nederdev, lullabot, buytaert.net. Voor een beginnende gebruiker zijn zulke verwijzingen verwarrend.

Opmaak

Gebruik cursief (de <em> tag) om nadruk te leggen. Gebruik geen onderstrepingen (de <ul> tag).
Gebruik <ol> lijsten voor stapsgewijze instructies.
Omring HTML-, CSS- en PHP-code met de <code> tags.

Paden

Geef het pad dat de lezer moet volgen om bepaalde acties uit te voeren
Beheren > Inhoudelijk beheer > Inhoud
Markeer paden schuingedrukt (omring het pad met <em> tags).
Gebruik de Nederlandse namen van de links die de lezer moet volgen. Omdat sommigen een Drupalinstallatie in het Engels hebben voeg je een voorbeeldlink toe
Beheren > Inhoudelijk beheer > Inhoud (http://www.example.com/admin/content/node).

Actieve zinnen

Hou je tekst leesbaar door een actieve zinnen te gebruiken.

Je doet dat door mensen of zaken als onderwerp te gebruiken.

Niet: Foutberichten worden daarna vastgelegd in de logs.
Wel: De module watchdog registreert foutberichten in de logs.
Niet: Dit is een Boolean om aan te geven of een node op de voorpagina moet worden weergegeven.
Wel: Deze Boolean bepaalt of een node op de voorpagina komt.

Passieve zinnen herken je aan het onnodige gebruik van "worden" of "zijn". Deze woorden vaak weglaten.

Aanspreekvorm

Spreek de lezer aan met "je".

Je zult als snel de enorme mogelijkheden ontdekken die Views voor jouw website te bieden heeft

Namen van modules

Gebruik de letterlijke naam van de module.
Gebruik een modulenaam als een eigennaam.
Vertaal de naam van een module niet.

Wel: Pathauto
Niet: Automatische padenModulenamen beginnen met een hoofdletter.

Wel: Views
Niet: views

Samenstellingen van modulenamen en zelfstandige naamwoorden schrijf je aan elkaar.

Bijvoorbeeld: Webforminstellingen

Verwijzen naar de website drupal.be of drupal.nl

Verwijs naar de website met drupal.be of drupal.nl.

Koppelteken

Gebruik een koppelteken tussen afkortingen en een zelfstandig naamwoord.

CSS-stijlen, HTML-tags, PHP-code

Gebruik eenvoudige woorden

Gebruik eenvoudige woorden waar dat mogelijk is.