Schrijf voor Snel.com – Tutorial Schrijfrichtlijnen

Estimated reading time: 2 min

Snel.com’s Schrijfrichtlijnen

We willen ervoor zorgen dat onze knowledge base-artikelen een consistente stijl en kwaliteit hebben, daarom hebben we de onderstaande richtlijnen ontwikkeld. Met deze richtlijnen leggen we uit aan welke structuur, stijl en tone of voice jouw teksten moeten voldoen.

Deze richtlijn bestaat uit drie onderdelen:

  • Schrijfstijl
  • Structuur
  • Opmaak

Stijlen:

De knowledge base artikelen moeten worden geschreven voor alle ervaringsniveaus. Dit houdt in dat de tutorial gedetailleerde informatie moet bevatten zonder te veronderstellen dat de lezer al over voldoende technische kennis beschikt of het onderwerp al kent. Het is belangrijk dat je niet vergeet om elke commando toe te voegen (vanaf de eerste SSH-verbinding tot de laatst werkende configuratie).

Technisch correct

Het is belangrijk dat je uitlegt waarom de lezer een opdracht moet uitvoeren en waarom hij bijvoorbeeld een configuratie of bestand moet aanpassen. De commando’s en stappen moeten vanaf het begin tot aan het eind volledig duidelijk zijn. De opdrachten van de tutorial moeten uitgevoerd worden op een nieuwe server, het is belangrijk dat de commando's vanaf het begin goed werken.

Vriendelijk en formeel

Zorg ervoor dat jouw tutorial leesvriendelijk is maar dat de toon wel formeel blijft. Gebruik de eerste persoon meervoud in je artikelen (we starten nu) of tweede persoon (je configureert nu) etc.

Structuur

Alle tutorials moeten een consistente structuur hebben. Houd de onderstaande volgorde aan in jouw artikelen:

  • Titel
  • Introductie / leg uit wat het doel is van de tutorial, waarom zou de lezer deze tutorial moeten volgen?
  • Vereisten
  • Stap 1 — Eerste stap uitleggen
  • Stap 2 — Tweede stap uitleggen etc
    ...
  • Conclusie

Titel en doel

Kies een titel die gerelateerd is aan het doel van de tutorial. Wanneer de lezer de titel van het artikel leest, moet hij kunnen concluderen waar het artikel over gaat. Als jouw tutorial bijvoorbeeld gaat over het installeren van een SSL-certificaat dan wil je waarschijnlijk zorgen voor een veilige verbinding. Dan zou je titel bijvoorbeeld “Hoe beveilig je jouw server met een Let’s Encrypt SSL’ kunnen zijn. Dit vertelt de lezer veel meer.

Vereisten

Het doel hier is om uit te leggen welke gegevens of informatie de lezer nodig heeft alvorens hij begint met het uitvoeren van de tutorial. Dit kan aan de hand van van een lijst met opsommingen.

De opsommingslijst kan er bijvoorbeeld als volgt uitzien:

  • De benodigde gegevens voor de initiële installatie of de installatie van de server.
  • Software-installaties en configuraties.
  • Vereiste SSL-certificaten etc.

Zorg ervoor dat de vereisten van jouw tutorial wel correct en compleet zijn. Mocht je tijdens jouw test een aantal dingen wijzigen, vergeet dan niet om dit op te nemen in deze lijst.

Stappen

In dit gedeelte beschrijf je welke stappen de lezer moet uitvoeren. Omschrijf hier wat de stap inhoudt en waarom de lezer deze stap moet uitvoeren om het algemene doel van de tutorial te bereiken.

Conclusie

Leg hier uit wat de lezer heeft bereikt met jouw tutorial. Vergeet niet om uit te leggen of de lezer ook nog andere stappen kan uitvoeren, je kunt de lezer bijvoorbeeld ook verwijzen naar gerelateerde knowledge base artikelen van Snel.com.

Codeblokken

Maak codeblokken voor de onderstaande punten:

  • Commando's
  • Terminal output
  • Scripts
  • Text dialogen
  • Gebruik voor elke commando die de lezer moet uitvoeren een afzonderlijke codeblok.

Alinea opmaak

Gebruik vetgedrukte tekst voor:

  • Hostnamen, gebruikersnamen
  • GUI text
  • Lijst van termen
  • Stappen die moeten worden benadrukt

Inline codeblokken

Gebruik inline codeblokken voor:

  • Voorbeeld URLs
  • Pakketnamen
  • Bestandsnamen en paden
  • Portnamen
  • Toetsenbord aanslagen moeten in grote letters geschreven worden, bijv, ENTER of DELETE

Afbeeldingen

Volg de onderstaande richtlijnen wanneer je een afbeelding toevoegt voor jouw tutorial.

  • Gebruik.png formaat
  • Upload jouw afbeeldingen via imgur
  • Gebruik consistente hoogtes en breedtes, the afbeelding mag niet groter zijn dan 600px

Maak geen screenshots van code afbeeldingen of output afbeeldingen. Je kunt bijvoorbeeld wel screenshots maken van GUI afbeeldingen of server setups.

Was this article helpful?
Dislike 0
Views: 48

Lees Interacties

Geef een reactie

Het e-mailadres wordt niet gepubliceerd. Vereiste velden zijn gemarkeerd met *