Richtlinien für Sprache und Stil
Eine große Anzahl an Personen, darunter IT-Experten und Entwickler, lesen Ihre .NET-Dokumentationen, um .NET zu erlernen und für ihre reguläre Arbeit zu verwenden. Ihr Ziel ist es, eine großartige Dokumentation zu erstellen, die den Lesern hilft. Diese Richtlinien sollen Ihnen dabei helfen. Der Styleguide enthält folgende Empfehlungen:
Verwenden eines Gesprächstons
Der folgende Abschnitt ist im Gesprächston gehalten. Der Abschnitt danach weist einen eher wissenschaftlichen Schreibstil auf.
Angemessener Stil
Die Dokumentation soll in einem Gesprächston geschrieben werden. Sie sollen sich beim Lesen der Tutorials oder Erklärungen so fühlen, als wären Sie im Gespräch mit dem Autor. Die Dokumentation sollte für Sie informell, dialogorientiert und informativ sein. Als Leser sollten Sie sich fühlen, als würden Sie dem Autor beim Erklären der Konzepte zuhören.
Unangemessener Stil
Im Kontrast zum Gesprächsstil steht der Stil, der für gewöhnlich bei wissenschaftlichen Behandlungen technischer Themen verwendet wird. Diese Ressourcen sind zwar sehr hilfreich, allerdings schreiben die Autoren solcher Artikel in einem Stil, der sich stark von Microsoft-Dokumentationen unterscheidet. Wenn man eine wissenschaftliche Zeitschrift liest, trifft man auf einen ganz anderen Schreibstil. Man fühlt sich eher, als würde man einen langweiligen Bericht zu einer trockenen Thematik lesen.
Schreiben in der zweiten Person
Der folgende Absatz ist in der zweiten Person geschrieben. Der darauffolgende Absatz verwendet die dritte Person. Schreiben Sie in der zweiten Person.
Angemessener Stil
Schreiben Sie Ihre Artikel so, dass Sie Ihre Leser direkt ansprechen. Verwenden Sie häufig die zweite Person (wie in diesen beiden Sätzen). Das heißt nicht, dass Sie immer das Wort „Sie“ verwenden sollen. Schreiben Sie direkt an den Leser. Schreiben Sie Sätze im Imperativ. Erzählen Sie dem Leser, was er lernen soll.
Unangemessener Stil
Ein Autor könnte sich auch dazu entscheiden, in dritter Person zu schreiben. In diesem Modell, muss der Autor ein Pronomen oder Nomen finden, mit dem er sich auf den Leser beziehen kann. Leser empfinden diesen Stil meist als weniger ansprechend und weniger unterhaltsam.
Verwenden von Aktiv
Schreiben Sie Ihre Artikel im Aktiv. Das heißt, das Subjekt des Satzes führt die Aktion (das Verb) im Satz aus. Dies steht im Gegensatz zum Passiv, bei dem der Satz so aufgebaut ist, dass die Aktion sich auf das Subjekt auswirkt. Vergleichen Sie die folgenden zwei Beispiele:
Der Compiler transformiert den Quellcode in eine ausführbare Datei.
Der Quellcode wurde vom Compiler in eine ausführbare Datei transformiert.
Im ersten Satz wird das Aktiv verwendet. Der zweite Satz wurde im Passiv geschrieben. (Beide Sätze stellen ein weiteres Beispiel der jeweiligen Stile dar.)
Das Aktiv wird empfohlen, da es einfacher zu lesen ist. Das Passiv kann schwerer zu lesen sein.
Schreiben für Leser, die möglicherweise nur über ein begrenztes Vokabular verfügen
Ihre Artikel erreichen eine internationale Zielgruppe. Viele Ihrer Leser sind keine Muttersprachler und verfügen möglicherweise nicht über dasselbe Vokabular wie Sie.
Allerdings schreiben Sie für technische Experten. Sie können davon ausgehen, dass Ihre Leser über Programmierkenntnisse und das spezifische Vokabular von Programmierbegriffen verfügen. Begriffe wie „objektorientierte Programmierung“, „Klasse“, „Objekt“, „Funktion“ und „Methode“ können als bekannt vorausgesetzt werden. Dennoch besitzt nicht jeder Leser einen Abschluss als Diplominformatiker. Wenn Sie Begriffe wie „idempotent“ verwenden, sollten Sie diese definieren, beispielsweise folgendermaßen:
Die Methode
Close()ist idempotent, das heißt, wenn Sie sie wiederholt aufrufen, bleibt die Auswirkung unverändert.
Vermeiden von Futur
In einigen Sprachen entspricht das Konzept des Zukunftstempus nicht dem Englischen. Die Verwendung des Zukunftstempus kann das Lesen Ihrer Dokumentationen erschweren. Wenn Sie das Futur verwenden, stellt sich außerdem an einem Punkt die Wann-Frage. Wenn Sie schreiben „PowerShell zu lernen, wird sich für Sie lohnen“, stellt der Leser sich natürlich die Frage „Wann wird es sich lohnen?“. Schreiben Sie stattdessen „Es lohnt sich, PowerShell zu lernen“.
Was ist es, und was tut es?
Immer, wenn Sie den Lesern ein neues Konzept vorstellen, definieren Sie zunächst das Konzept, bevor Sie erklären, inwiefern es nützlich ist. Für die Leser ist es wichtig, zu verstehen, was etwas ist, bevor sie die Vorteile (oder andere Aspekte) verstehen können.