Zur Dokumentation beitragen

Ein Beitrag zur Dokumentation gehört zu den wertvollsten Tätigkeiten überhaupt, denn er hilft anderen dabei, das Framework zu verstehen.

Wie schreibt man?

Die Dokumentation ist in erster Linie für Menschen gedacht, die das Thema neu kennenlernen. Deshalb sollte sie einige wichtige Punkte erfüllen:

• Beginnen Sie mit einfachen und allgemeinen Begriffen. Zu fortgeschritteneren Themen gehen Sie erst zum Schluss über.
• Versuchen Sie, das Thema so verständlich wie möglich zu erklären. Erklären Sie es zum Beispiel zuerst einem Kollegen.
• Geben Sie nur die Informationen an, die der Benutzer für das jeweilige Thema wirklich braucht.
• Überprüfen Sie, dass Ihre Informationen zutreffen. Testen Sie jedes Stück Code.
• Fassen Sie sich kurz – halbieren Sie, was Sie geschrieben haben. Und dann ruhig noch einmal.
• Gehen Sie sparsam mit Hervorhebungen um, von fettem Text bis zu Rahmen wie .[note].
• Halten Sie sich in den Codebeispielen an den Coding Standard.

Machen Sie sich außerdem mit der Syntax vertraut. Für eine Vorschau des Artikels beim Schreiben können Sie den Vorschau-Editor verwenden.

Sprachversionen

Englisch ist die Hauptsprache, Ihre Änderungen sollten also idealerweise auf Englisch sein. Wenn Englisch nicht Ihre Stärke ist, nutzen Sie den DeepL Translator, und andere werden Ihren Text durchsehen.

Die Übersetzung in die anderen Sprachen erfolgt automatisch, nachdem Ihre Änderung angenommen und abgeschlossen ist.

Triviale Änderungen

Um zur Dokumentation beizutragen, brauchen Sie ein Konto auf GitHub.

Am einfachsten nehmen Sie eine kleine Änderung in der Dokumentation über die Links am Ende jeder Seite vor:

• Auf GitHub anzeigen öffnet die Quellfassung der Seite auf GitHub. Dann genügt die Taste E, um mit dem Bearbeiten zu beginnen (Sie müssen bei GitHub angemeldet sein).
• Vorschau öffnen öffnet einen Editor, in dem Sie sofort das endgültige Aussehen sehen.

Da der Vorschau-Editor Änderungen nicht direkt auf GitHub speichern kann, müssen Sie den Quelltext nach dem Bearbeiten in die Zwischenablage kopieren (über die Schaltfläche In die Zwischenablage kopieren) und ihn dann in den Editor auf GitHub einfügen. Unter dem Bearbeitungsfeld befindet sich ein Formular zum Absenden. Vergessen Sie dort nicht, kurz zusammenzufassen und zu begründen, warum Sie die Änderung vorgenommen haben. Nach dem Absenden entsteht ein Pull Request (PR), der sich weiter bearbeiten lässt.

Größere Änderungen

Statt sich allein auf die Oberfläche von GitHub zu verlassen, ist es besser, die Grundlagen im Umgang mit dem Versionsverwaltungssystem Git zu beherrschen. Wenn Sie sich mit Git nicht auskennen, können Sie sich git – the simple guide ansehen und einen der vielen verfügbaren grafischen Clients in Betracht ziehen.

Die Dokumentation bearbeiten Sie so:

1. Erstellen Sie auf GitHub einen Fork des Repositorys nette/docs.
2. Klonen Sie dieses Repository auf Ihren Computer.
3. Nehmen Sie die Änderungen dann im passenden Branch vor.
4. Prüfen Sie den Text mit dem Werkzeug Code-Checker auf überflüssige Leerzeichen.
5. Speichern (committen) Sie die Änderungen.
6. Wenn Sie mit den Änderungen zufrieden sind, pushen Sie sie zu GitHub in Ihren Fork.
7. Senden Sie sie von dort in das Repository nette/docs, indem Sie einen Pull Request (PR) erstellen.

Üblicherweise erhalten Sie Kommentare mit Vorschlägen. Behalten Sie die vorgeschlagenen Änderungen im Blick und arbeiten Sie sie ein. Fügen Sie die vorgeschlagenen Änderungen als neue Commits hinzu und pushen Sie sie erneut zu GitHub. Erstellen Sie niemals einen neuen Pull Request, nur um einen bestehenden zu ändern.

Struktur der Dokumentation

Die gesamte Dokumentation liegt auf GitHub im Repository nette/docs. Die aktuelle Fassung befindet sich im Branch master, ältere Versionen in Branches wie doc-3.x oder doc-2.x.

Der Inhalt jedes Branches ist in Hauptordner unterteilt, die den einzelnen Bereichen der Dokumentation entsprechen. So entspricht etwa application/ der Adresse https://doc.nette.org/en/application, latte/ der Adresse https://latte.nette.org usw. Jeder dieser Ordner enthält Unterordner für die Sprachversionen (cs, en, …) und optional einen Unterordner files mit Bildern, die sich in die Seiten der Dokumentation einbinden lassen.