Snel aan de slag met stijl en toon

Deze stijlgids om snel aan de slag te gaan vereist weinig tijd, maar geeft een goed inzicht in hoe u de belangrijkste concepten voor de Docs-stijl toepast bij het schrijven van artikelen voor docs.microsoft.com. Deze richtlijnen gelden voor nieuwe documentatie en voor het bijwerken van bestaande documentatie.

Houd u minimaal aan de volgende vereisten:

  • Controleer de spelling en grammatica in uw artikelen. Hiervoor kunt u de tekst kopiëren en plakken in Word.
  • Gebruik een alledaagse, vriendelijke toon alsof u tegen een persoon praat.
  • Gebruik eenvoudige zinnen. Deze zijn gemakkelijker te begrijpen en kunnen beter worden vertaald door zowel mensen als systemen.

De Microsoft-principes voor de toon gebruiken

We streven ernaar aan deze principes te voldoen als we technische inhoud voor docs.microsoft.com schrijven. Misschien lukt het niet altijd, maar we blijven het proberen.

  • Richt u op het doel: klanten hebben een bepaald doel voor ogen wanneer ze onze documentatie raadplegen. Zorg ervoor dat u voordat u begint te schrijven helder voor ogen hebt wie de klant is en welke taak hij/zij probeert uit te voeren. Schrijf vervolgens uw artikel om die specifieke klant te helpen die specifieke taak uit te voeren.

  • Gebruik alledaagse woorden: probeer natuurlijke taal te gebruiken en kies de woorden die uw klanten zouden gebruiken. Gebruik niet al te formeel taalgebruik, maar houd het wel technisch. Geef voorbeelden die nieuwe concepten uitleggen.

  • Houd het kort: gebruik niet meer woorden dan nodig. Wees positief en gebruik geen extra woorden of veel kwalificerende elementen. Houd zinnen kort en beknopt. Houd uw artikel gericht. Als een taak een kwalificerend element heeft, zet u het aan het begin van de zin of alinea. Gebruik ook zo weinig mogelijk opmerkingen. Gebruik een schermopname wanneer dit tekst bespaart.

  • Zorg ervoor dat uw artikel gemakkelijk te scannen is: vermeld eerst het belangrijkste. Gebruik secties om lange procedures op te splitsen in overzichtelijke groepen met stappen. (Procedures met meer dan 12 stappen zijn waarschijnlijk te lang.) Gebruik een schermopname als de tekst hierdoor duidelijker wordt.

  • Toon inlevingsvermogen: gebruik een behulpzame toon in het artikel en beperk disclaimers tot het minimum. Wees eerlijk over wat frustrerend voor klanten kan zijn. Zorg ervoor dat u zich in het artikel richt op wat belangrijk is voor de klant. Vermijd een puur technisch verhaal.

Hier vindt u handige referentie met een samenvatting van de principes voor de toon. Gebruik de informatie om de principes te implementeren. Ga naar de video's met trainingen voor de toon die u in eigen tempo kunt volgen, voor informatie over hoe u de principes voor de toon in uw eigen teksten integreert.

Rekening houden met lokalisatie en machinevertalingen

Onze technische artikelen worden in diverse talen vertaald en sommige worden aangepast voor bepaalde markten of regio's. Mensen kunnen ook machinevertalingen op internet gebruiken om de technische artikelen te lezen. Houd daarom bij het schrijven de volgende richtlijnen in gedachten:

  • Controleer of het artikel geen grammatica-, spel- of interpunctiefouten bevat; dit is iets wat we altijd moeten doen. Sommige Markdown-editors (zoals Markdown Pad 2.0) hebben basisfuctionaliteit voor de spellingcontrole, maar het is beter de weergegeven HTML-inhoud van het artikel in Word te plakken, waar de spelling- en grammaticacontrole geavanceerder zijn.

  • Houd de zinnen zo kort mogelijk: samengestelde zinnen of meerdere bijzinnen achter elkaar maken een vertaling moeilijk. Splits zinnen op als u dit kunt doen zonder teveel te herhalen of vreemd te klinken. Artikelen moeten natuurlijk ook niet in onnatuurlijke taal worden geschreven.

  • Gebruik een eenvoudige en consistente zinsconstructie: consistentie is beter als tekst moet worden vertaald. Vermijd haakjes en ingevoegde opmerkingen, en zorg ervoor dat het onderwerp zo dicht mogelijk aan het begin van de zin staat. Bekijk een paar gepubliceerde artikelen. Als een artikel een beschrijvende, gemakkelijk te lezen stijl heeft, kunt u dit artikel als voorbeeld gebruiken.

  • Zorg ervoor dat uw formulering en hoofdlettergebruik consistent zijn: ook hier geldt weer dat consistentie heel belangrijk is. Gebruik alleen aan het begin van een zin een hoofdletter.

  • Laat geen 'kleine woorden' weg: woorden die klein en onbelangrijk lijken (bijvoorbeeld 'een', 'de', 'die' en 'is'), zijn wel belangrijk voor machinevertalingen. Laat ze dus niet weg.

Waar u verder nog op moet letten bij de stijl en toon

  • Splits stappen niet op met commentaar of terzijdes.

  • Als stappen codefragmenten bevatten, plaatst u aanvullende informatie over de stap als commentaar in de code. Hierdoor wordt de te lezen hoeveelheid tekst beperkt. Bovendien is het handig belangrijke informatie in de code op te nemen zodat wanneer mensen op een later tijdstip de code raadplegen, ze deze informatie ook meteen zien.

  • Gebruik officiële product- en servicenamen, zoals 'Microsoft Intune' of 'Microsoft Advanced Threat Analytics'. U kunt ook alleen 'Intune' of 'Advanced Threat Analytics' gebruiken.

  • Gebruik geen afkortingen in plaats van de officiële productnamen. Gebruik bijvoorbeeld niet 'Azure MS' in plaats van 'Azure Mobile Services' of 'AAD' in plaats van 'Azure Active Directory'. Als er al een acroniem bestaat, zoals bij 'Azure AD', gebruikt u de eerste keer de volledige vorm met het acroniem tussen haakjes: 'Azure Active Directory (AD)'. Gebruik alle volgende keren 'Azure AD'. Probeer echter in het algemeen acroniemen te vermijden. Dit is alleen maar verwarrend.

  • Gebruik een zin voor alle titels en kopteksten.

  • Gebruik 'aanmelden' en niet 'inloggen'.

  • Gebruik de tekst 'als volgt' in elke zin die voorafgaat aan een lijst of codefragment.

Gelokaliseerde documentatie

Volgende stappen