Schrijf voor Snel.com – Tutorial Schrijfrichtlijnen

Snel.com’s Schrijfrichtlijnen

We willen ervoor zorgen dat onze knowledge base artikelen een consistente stijl en kwaliteit hebben, daarom hebben we de onderstaande tutorial schrijfrichtlijnen 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 lees vriendelijk 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 en opmaak

Alle tutorials moeten een consistente structuur hebben en ten minste 300 woorden bevatten. Aangezien de naam van het artikel in onze CSS reeds aangemerkt wordt als H1, hou je de volgende opmaak aan in de body van jouw artikelen:

• H2 – Titel - Max. 70 tekens

• Txt – Introductie — leg uit wat het doel is van de tutorial, waarom zou de lezer deze tutorial moeten volgen?

• H2 – Vereisten - Max. 70 tekens — 

  • Txt – Welke vereisten zijn er om deze tutorial op te kunnen volgen.

• H3 – Stap 1 —

  • Txt- Leg de eerste stap uit.

• H3 – Stap 2 —

  • Txt – Leg de tweede stap uit.
    …

• H3 – Stap .. —

  • Leg uit

• H3 – Conclusie —

  • Txt – Vorm 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 bij voorkeur 4/5 woorden. 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 opsomming 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.

De codeblokken staan in deze vorm <code class=”EnlighterJSRAW” data-enlighter-language=”generic”> Hier komt de tekst </code>

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 600p

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

Linking

We linken enkel extern met een “Nofollow”-tag. Probeer altijd interne links (vooral naar onze productpagina’s) toe te voegen aan je artikel. Link bij voorkeur boven de vouw (in de eerste of tweede alinea).