Wie man zur Dokumentation beiträgt

Beiträge zur Dokumentation sind eine der lohnendsten Tätigkeiten, da Sie anderen helfen, das Framework zu verstehen.

Wie schreibt man?

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

• Beginnen Sie mit dem Einfachen und Allgemeinen. Gehen Sie erst am Ende zu fortgeschritteneren Themen über.
• Versuchen Sie, die Sache so gut wie möglich zu erklären. Versuchen Sie zum Beispiel, das Thema zuerst einem Kollegen zu erklären.
• Geben Sie nur die Informationen an, die der Benutzer tatsächlich zum jeweiligen Thema wissen muss.
• Überprüfen Sie, ob Ihre Informationen tatsächlich wahr sind. Testen Sie jeden Code.
• Seien Sie prägnant – kürzen Sie, was Sie schreiben, auf die Hälfte. Und dann ruhig noch einmal.
• Sparen Sie mit Hervorhebungen aller Art, von Fettdruck bis hin zu Rahmen wie .[note].
• Halten Sie sich in den Codebeispielen an den Codierungsstandard.

Machen Sie sich auch mit der Syntax vertraut. Für die Vorschau eines Artikels während des Schreibens können Sie den Editor mit Vorschau verwenden.

Sprachversionen

Die Hauptsprache ist Englisch. Ihre Änderungen sollten daher idealerweise sowohl auf Tschechisch als auch auf Englisch erfolgen. Wenn Englisch nicht Ihre Stärke ist, verwenden Sie den DeepL Translator und andere werden den Text für Sie überprüfen.

Die Übersetzung in andere Sprachen erfolgt automatisch nach Genehmigung und Feinabstimmung Ihrer Änderung.

Triviale Änderungen

Um zur Dokumentation beizutragen, ist ein Konto auf GitHub erforderlich.

Der einfachste Weg, eine kleine Änderung in der Dokumentation vorzunehmen, ist die Verwendung der Links am Ende jeder Seite:

• Auf GitHub anzeigen öffnet die Quellcodedatei der jeweiligen Seite auf GitHub. Drücken Sie dann einfach die Taste E und Sie können mit der Bearbeitung beginnen (Sie müssen bei GitHub angemeldet sein).
• Vorschau öffnen öffnet den Editor, in dem Sie auch gleich die resultierende visuelle Darstellung sehen.

Da der Editor mit Vorschau keine Möglichkeit hat, Änderungen direkt auf GitHub zu speichern, müssen Sie nach Abschluss der Bearbeitung den Quelltext in die Zwischenablage kopieren (mit der Schaltfläche Copy to clipboard) und ihn dann in den Editor auf GitHub einfügen. Unter dem Bearbeitungsfeld befindet sich ein Formular zum Senden. Vergessen Sie hier nicht, den Grund für Ihre Änderung kurz zusammenzufassen und zu erklären. Nach dem Senden entsteht ein sogenannter Pull Request (PR), der weiter bearbeitet werden kann.

Größere Änderungen

Besser als die Nutzung der GitHub-Oberfläche ist es, mit den Grundlagen der Arbeit mit dem Versionskontrollsystem Git vertraut zu sein. Wenn Sie nicht mit Git vertraut sind, können Sie sich den Leitfaden git – the simple guide ansehen und gegebenenfalls einen der vielen grafischen Clients nutzen.

Bearbeiten Sie die Dokumentation auf diese Weise:

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

Es ist üblich, dass Sie Kommentare mit Anmerkungen erhalten. Verfolgen Sie die vorgeschlagenen Änderungen und arbeiten Sie sie ein. Fügen Sie die vorgeschlagenen Änderungen als neue Commits hinzu und senden Sie sie erneut auf GitHub. Erstellen Sie niemals einen neuen Pull Request, um einen bestehenden Pull Request zu bearbeiten.

Struktur der Dokumentation

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

Der Inhalt jedes Branches ist in Hauptordner unterteilt, die die einzelnen Bereiche der Dokumentation repräsentieren. Zum Beispiel entspricht application/ https://doc.nette.org/de/application, latte/ entspricht https://latte.nette.org usw. Jeder dieser Ordner enthält Unterordner, die die Sprachversionen (cs, en, …) darstellen, und gegebenenfalls einen Unterordner files mit Bildern, die in die Seiten der Dokumentation eingefügt werden können.