Zur Dokumentation beitragen

Die Mitarbeit an der Dokumentation ist eine der wertvollsten Aktivitäten, da sie anderen hilft, den Rahmen zu verstehen.

Wie schreibt man?

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

• Beginnen Sie mit einfachen und allgemeinen Themen. Gehen Sie am Ende zu fortgeschritteneren Themen über
• Versuchen Sie, das Thema so klar wie möglich zu erklären. Versuchen Sie zum Beispiel, das Thema zuerst einem Kollegen zu erklären.
• Geben Sie nur die Informationen, die der Benutzer für ein bestimmtes Thema tatsächlich benötigt
• Stellen Sie sicher, dass Ihre Informationen korrekt sind. Testen Sie jeden Code
• Seien Sie prägnant – kürzen Sie, was Sie schreiben, um die Hälfte. Und dann können Sie es gerne wiederholen
• Verwenden Sie Hervorhebungen sparsam, von fetten Schriftarten bis hin zu Rahmen wie .[note]
• Befolgen Sie den Kodierungsstandard im Code

Lernen Sie auch die Syntax. Für eine Vorschau des Artikels während des Schreibens, können Sie die Vorschau-Editor verwenden.

Sprachmutationen

Englisch ist die Hauptsprache, daher sollten Ihre Änderungen auf Englisch erfolgen. Wenn Englisch nicht Ihre Stärke ist, verwenden Sie DeepL Translator und andere werden Ihren Text überprüfen.

Die Übersetzung in andere Sprachen erfolgt automatisch nach der Genehmigung und Feinabstimmung Ihrer Bearbeitung.

Triviale Bearbeitungen

Um zur Dokumentation beizutragen, müssen Sie ein Konto auf GitHub haben.

Der einfachste Weg, eine kleine Änderung an der Dokumentation vorzunehmen, ist die Verwendung der Links am Ende 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 einen Editor, in dem Sie sofort die endgültige 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 Editor auf GitHub einfügen. Unterhalb des Bearbeitungsfeldes befindet sich ein Formular zum Einreichen. Vergessen Sie hier nicht, den Grund für Ihre Bearbeitung kurz zusammenzufassen und zu erläutern. Nach dem Einreichen wird ein sogenannter Pull Request (PR) erstellt, der weiter bearbeitet werden kann.

Größere Bearbeitungen

Es ist sinnvoller, mit den Grundlagen der Arbeit mit dem Versionskontrollsystem Git vertraut zu sein, als sich ausschließlich auf die GitHub-Schnittstelle zu verlassen. Wenn Sie mit Git nicht vertraut sind, können Sie den Leitfaden Git – die einfache Anleitung zu Rate ziehen und die Verwendung eines der vielen verfügbaren grafischen Clients in Betracht ziehen.

Bearbeiten Sie die Dokumentation auf die folgende Weise:

1. Erstellen Sie auf GitHub einen Fork des nette/docs-Repository
2. klonen Sie dieses Repository auf Ihren Computer
3. nehmen Sie dann Änderungen im entsprechenden Zweigvor
4. Prüfen Sie mit dem Code-Checker auf zusätzliche Leerzeichen im Text
5. speichern (committen) Sie die Änderungen
6. wenn du mit den Änderungen zufrieden bist, veröffentliche sie auf GitHub in deinem Fork
7. übermitteln Sie sie von dort aus an das Repository nette/docs, indem Sie einen pull request (PR) erstellen

Es ist üblich, dass Sie Kommentare mit Vorschlägen erhalten. Behalten Sie die vorgeschlagenen Änderungen im Auge und nehmen Sie sie auf. Fügen Sie die vorgeschlagenen Änderungen als neue Commits hinzu und senden Sie sie erneut an GitHub. Erstellen Sie niemals einen neuen Pull Request, nur um einen bestehenden zu ändern.

Struktur der Dokumentation

Die gesamte Dokumentation befindet sich auf GitHub im Repository nette/docs. Die aktuelle Version befindet sich im Master-Zweig, während ältere Versionen in Zweigen wie doc-3.x, doc-2.x zu finden sind.

Der Inhalt jedes Zweigs ist in Hauptordner unterteilt, die einzelne 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 Sprachmutationen (cs, en, …) und optional einen Unterordner files mit Bildern, die in die Seiten der Dokumentation eingefügt werden können.