Dokumentation schreiben

An der Dokumentation mitzuarbeiten ist eine der lohnendsten Tätigkeiten, weil Sie anderen helfen, das Framework zu verstehen.

Schnelle Bearbeitungen

Der einfachste Weg, den Text in der Dokumentation zu bearbeiten, ist die Verwendung der Links am unteren Rand jeder Seite:

• Auf GitHub anzeigen öffnet die Quellversion der Seite auf GitHub. Klicken Sie dann einfach auf die Schaltfläche E und Sie können mit der Bearbeitung beginnen (Sie müssen bei GitHub angemeldet sein)
• Vorschau öffnen öffnet den Editor, wo Sie auch die resultierende visuelle Form sehen können.

Da der Vorschau-Editor nicht die Möglichkeit bietet, Änderungen direkt auf GitHub zu speichern, müssen Sie den Quelltext in die Zwischenablage kopieren (mit der Schaltfläche In die Zwischenablage kopieren) und dann in den GitHub-Editor einfügen, wenn Sie mit der Bearbeitung fertig sind. Unterhalb des Bearbeitungsfeldes befindet sich ein Formular zum Absenden. Stellen Sie sicher, dass Sie den Grund für Ihre Bearbeitung hier kurz zusammenfassen und erklären. Nach dem Absenden wird ein Pull Request erstellt, der weiter bearbeitet werden kann.

Wie schreibt man?

Die Dokumentation richtet sich vor allem an Personen, die mit dem Thema noch nicht vertraut sind. Daher sollte sie mehrere wichtige Punkte erfüllen:

• Beginnen Sie beim Schreiben mit dem Einfachen und Allgemeinen. Gehen Sie am Ende zu fortgeschritteneren Themen über.
• Fügen Sie nur die Informationen ein, die der Nutzer wirklich über das Thema wissen muss.
• Vergewissern Sie sich, dass Ihre Informationen tatsächlich wahr sind. Testen Sie den Code zuerst, bevor Sie ihn weitergeben.
• Seien Sie prägnant – reduzieren Sie Ihren Text auf die Hälfte. Und dann wiederholen Sie es.
• Versuchen Sie, den Sachverhalt so gut wie möglich zu erklären. Versuchen Sie zum Beispiel, das Thema zuerst einem Kollegen zu erklären.
• Sparen Sie sich die Textmarker aller Art, von Fettschrift bis zu Kästchen wie .[note].

Behalten Sie diese Punkte während des gesamten Schreibens im Hinterkopf. Machen Sie sich auch mit der Syntax vertraut. Sie können einen Vorschau-Editor verwenden, um den Artikel während des Schreibens zu überprüfen.

Beachten Sie zusätzlich zu den oben genannten Punkten auch die folgenden Richtlinien:

• Englisch ist die Hauptsprache, daher sollten Sie Ihre Änderungen in beiden Sprachen vornehmen. Wenn Englisch nicht Ihre Stärke ist, verwenden Sie DeepL Translator und andere werden Ihren Text Korrektur lesen.
• Befolgen Sie den Kodierungsstandard in den Beispielen.
• Schreiben Sie die Namen von Variablen, Klassen und Methoden auf Englisch.
• Namespaces sollten bei der ersten Erwähnung angegeben werden.
• Versuchen Sie, Ihren Code so zu formatieren, dass keine Bildlaufleisten angezeigt werden.
• Beziehen Sie sich für die Dokumentation nur auf die Dokumentation oder www.

Beitragen zur Dokumentation

Sie müssen ein GitHub-Konto haben, um zur Dokumentation beizutragen. Sie können einfache Änderungen direkt in der Schnittstelle vornehmen.

Es ist jedoch sinnvoller, die Grundlagen der Arbeit mit dem Versionsverwaltungssystem Git zu kennen. Wenn Sie mit Git nicht vertraut sind, können Sie sich diese Kurzanleitung ansehen: git – the simple guide, oder eines der vielen grafischen Tools verwenden: GIT – GUI-Clients.

Beginnen Sie mit der Bearbeitung der Dokumentation, indem Sie einen Fork des nette/docs-Repositorys erstellen und diesen auf Ihren Computer klonen. Nehmen Sie dann Änderungen im entsprechenden Zweig vor, übertragen Sie die Änderungen, schieben Sie sie in Ihr GitHub-Repository und senden Sie eine Pull-Anfrage an das ursprüngliche Repository nette/docs.

Vor jedem Pull-Request sollten Sie den Code-Checker ausführen, um den Text auf zusätzliche Leerzeichen zu überprüfen.

Aufbau der Dokumentation

Die gesamte Dokumentation wird auf GitHub im Repository nette/docs gehostet. Die aktuelle Version befindet sich im Master, ältere Versionen befinden sich in Zweigen wie doc-3.x, doc-2.x.

Der Inhalt jedes Zweigs ist in Hauptordner unterteilt, die die einzelnen Bereiche der Dokumentation repräsentieren. So entspricht beispielsweise application/ dem Ordner https://doc.nette.org/en/application, latte/ dem Ordner https://latte.nette.org, usw. Jeder dieser Ordner enthält Unterordner für die Sprachversionen (cs, en, …) und möglicherweise einen Unterordner files mit Bildern, die in die Dokumentationsseiten eingebettet werden können.