Sprache und Stil

Sprache
Stil

Nach der Flut von DocBook-Informationen im vorigen Abschnitt, werden wir unsere Aufmerksamkeit einem anderen wichtigen Aspekt des Schreibens widmen: Sprache und Stil (in diesem Abschnitt) sowie Copyrights (im nächsten Abschnitt).

Sprache

Die Firebird Community ist sehr verschieden und besteht aus Menschen mit vielen verschiedenen Muttersprachen. Wenn Sie Ihre Dokumentation in einer anderen Sprache als der eigenen schreiben, werden Sie wahrscheinlich einige Fehler machen. Dies ist nicht katastrophal, aber man sollte zumindest versuchen, die Anzahl der Fehler zu reduzieren. Einige Strategien, die Ihnen dabei helfen, sind:

Benutzen Sie ein Wörterbuch! Einfach, effektiv und erstaunlicherweise keine Hightech.
Wenn Sie zwischen zwei Schreibweisen eines Wortes oder zwischen mehrere mögliche Versionen eines Ausdrucks schwanken, googeln Sie nach Alternativen und achten Sie auf deren Frequentierung. Folgen Sie Links, um zu sehen wie Muttersprachler das Wort oder den Ausdruck in ihren Texten verwenden.
Lassen Sie einen Muttersprachler über Ihren Text sehen und ggf. korrigieren.

Stil

Erwarten Sie nicht, einen Style Guide hier zu finden - ich wüsste nicht, wie man einen schreibt. Nur ein paar Hinweise und Tipps:

Versuchen Sie, in einfacher, alltäglicher Sprache, wo immer möglich zu schreiben. Vermeiden Sie schwierige Wörter, wenn es eine vertraute, einfache Alternative gibt.
Vermeiden Sie lange Sätze (über 25 Wörter), wenn Sie können. Vermeiden Sie vor allem zwei oder mehr lange Sätze unmittelbar nacheinander.
Seien Sie vorsichtig mit Konstrukten wie doppelter oder dreifacher Verneinung („Ich kann nicht leugnen, dass ich nicht unzufrieden bin“) und passiver Sprache („Vorsicht sollte geboten sein...“). Sie müssen diese nicht unter allen Umständen vermeiden, aber sie machen einen Satz schwer verständlich. Um dies zu verhindern, nutzen Sie positive („Ich bin zufrieden“) und aktive („Seien Sie vorsichtig...“) Sprache.
Verwenden Sie Listen für Aufzählungen, z.B. für:
- Eine Sammlung von Hinweisen und Tipps.
- Eine Reihe Beispiele (wie dieses hier).
- Schritte, die in einer Nummerierung erscheinen.
- Alternative Lösungsansätze für ein Problem.
Sind jedoch nur wenige Einträge zu nennen, verwenden Sie stattdessen reinen Text: „Meine Mutter liebt drei Männer: John, Dick und Dave.“
Nutzen Sie nicht zu viele Ausrufezeichen. Verwenden Sie niemals mehrere Ausrufezeichen oder Fragezeichen. Das ist ärgerlich!! Glauben Sie nicht auch??

Docwriter-Block

Manchmal wissen Sie, was Sie schreiben wollen, Sie haben alle Wörter, aber Sie bekommen den Satz nicht zusammen - Ihnen gelingt einfach kein Fluss. Das ist sehr frustrierend und es kann manchmal den Fortschritt Ihres Textes für viele Minuten blockieren. Und es ist umso frustrierender, weil Sie ja wissen was Sie Ihren Leser sagen wollen, aber Sie scheinen nicht in der Lage zu sein, einen anständigen Satz zu produzieren. Nach vielen schmerzhaften Erfahrungen dieser Art, habe ich die folgende Strategie entwickelt (nicht, dass ich glaube, ich wäre der erste):

Notieren Sie, was Sie in losen Sätzen und Wortbrocken sagen möchten. Machen Sie sich keine Gedanken über den Stil. Schreiben Sie einfach, was Sie dem Leser sagen wollen, stellen Sie sicher, dass alles da ist und in der richtigen Reihenfolge. Wenn Sie währenddessen merken, dass Sie bei einer Sache unsicher sind, machen Sie sich eine Bemerkung an diesem Punkt. Heben Sie Ihre Bemerkungen vom restlichen Text ab z. B. <<wie diesen>> oder !WIE DIESEN!

Dies kann in folgendem Text enden:

CVS bedeutet Concurrent Versions System (<<überprüfen!>>). Zweck: Verwaltung von Softwareversionen. Sie können es verwenden, allein oder in einer Gruppe. Sie müssen einen CVS-Client benutzen. Ein CVS-Client ist ein Programm, mit dem Sie auf ein CVS-Repository (<<Begriff erklären?>>) zugreifen können. Um herauszufinden, ob Sie einen CVS-Client auf Ihrem System installiert haben, geben Sie „ cvs “ auf der Kommandozeile ein. Wenn Sie keinen installiert haben, rufen Sie diese URL für den Download auf .... [etc., etc.]
Wenn Sie Bemerkungen eingefügt haben, kümmern Sie sich erst um diese. Prüfen Sie, ob CVS wirklich Concurrent Versions System bedeutet (tut es). Entscheiden Sie, ob Sie wirklich den Begriff „CVS repository“ an diesem Punkt erklären sollten (sollten Sie).
Gehen Sie nun nochmals über den Absatz und versuchen Sie, den Text fließender zu gestalten. Wahrscheinlich wird dies leichter sein als Sie glauben!
Wenn es noch etwas holprig aussiet, egal - besser holprig und klar als glatt-fließend und unpräzise. Vielleicht können Sie diese Passage bei einem späteren Besuch etwas schöner gestalten.

Dieser Ansatz funktioniert gut für mich. Wenn also auch mals auf diese Weise festhängen, probieren Sie es aus, hoffentlich wird es auch Ihnen helfen.