Snel aan de slag met stijl en spraak van Microsoft Learn

Deze quickstart is een korte handleiding voor het schrijven van technische inhoud voor publicatie op Microsoft Learn. Deze richtlijnen gelden voor nieuwe documentatie en voor het bijwerken van bestaande documentatie.

Best practices:

• Controleer de spelling en grammatica in uw artikelen. Hiervoor kunt u de tekst kopiëren en plakken in Microsoft Word.
• Gebruik een alledaagse, vriendelijke toon alsof u tegen een persoon praat.
• Gebruik eenvoudige zinnen. Als u gemakkelijk leesbare zinnen gebruikt, kan de lezer de instructies die u geeft, snel in de praktijk brengen.

De Microsoft-principes voor de toon gebruiken

We streven ernaar om deze principes te volgen wanneer we technische inhoud schrijven voor Microsoft Learn. 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 wanneer deze duidelijkheid toevoegt.
• 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.

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 een zin voor alle titels en kopteksten.
• Gebruik 'aanmelden' en niet 'inloggen'.
• Raadpleeg de Microsoft Writing Style Guide voor meer richtlijnen.

Gelokaliseerde documentatie

• Als u bijdraagt aan gelokaliseerde documentatie, raadpleegt u de globalisatieverwijzingen.
• Download de stijlgids in uw taal voor lokalisatierichtlijnen, informatie over de stijl en het gebruik van taal in technische publicaties en informatie over marktspecifieke opmaak van gegevens.
• Ga naar Microsoft-terminologie om te zoeken naar productspecifieke goedgekeurde terminologie of om de Microsoft-terminologieverzameling in uw taal te downloaden.
• Raadpleeg 'Global communications' in de Microsoft Writing Style Guide voor meer informatie over lokalisatie.

Notitie

De meeste gelokaliseerde documentatie biedt niet de mogelijkheid om via GitHub feedback te bewerken of te geven. Gebruik https://aka.ms/provide-feedback het formulier om feedback te geven over gelokaliseerde inhoud.