Verwendung der GitLab-Benutzeroberfläche für die komplexere Dokumentenpflege
Die Dokumentation muss mit zunehmendem Inhalt gepflegt werden. Autoren und Reviewer können über die GitLab-Weboberfläche einfach und effizient zur Dokumentation beitragen. Von der Web-IDE über die CI-Pipeline bis hin zur gemeinsamen Überprüfung gerenderter Webinhalte und der Freigabe von Seiten können Sie ungestört an guten Inhalten und der Dokumentationspflege arbeiten, ohne durch Installation und Konfiguration unterbrochen zu werden. Dieser Artikel setzt voraus, dass Sie bereits mit Git und Continuous Integration (CI) vertraut sind.
Pflege von Dokumentationen
Die Pflege von Dokumentationen kann viele Formen annehmen.
-
Technische Korrektheit
-
Aktualität
-
Kuratierung der Dokumentation in logischer Reihenfolge
-
Einheitlichkeit in der Präsentation
-
Standardvorlage, Attribute und Konventionen, die in allen Docs-Repos angewendet werden
-
Nutzung einer CI-Pipeline zur Automatisierung von Dokumentenqualitätsprüfungen
In den folgenden Abschnitten wird Schritt für Schritt erklärt, wie die Qualität der Fedora Docs-Repositories mithilfe der in GitLab integrierten Werkzeuge gepflegt und kontinuierlich verbessert werden kann.
GitLab Web-IDE
Die neue Web-IDE wurde im Rahmen der Veröffentlichung von GitLab 15.7 im Dezember 2022 eingeführt und bietet einen Datei-Explorer, einen Texteditor und eine Quellcodeverwaltung an einem Ort.
Explorer
Der Explorer im linken Bereich hilft dabei, die Repository-Struktur und die Dateiliste in Fedora Docs zu erkunden. Unabhängig vom verwendeten Repository ermöglicht die standardisierte Repository-Struktur den Mitwirkenden, schnell durch die Dateien zu navigieren und Querverweise zwischen mehreren Seiten herzustellen.
Texteditor
After making changes, go to the Source Control icon in the Activity Bar and click Changes under the Commit & Push button to view a list of files you changed in side-by-side view. If you made multiple commits, Changes indicate an overview of changes you have.
If you click Create MR, you will be forwarded to your fork to create merge request. Go to project option is suitable when you made small commits by stage and want to squash them into one.
CI-Pipeline
Automated test for Docs triggers syntax validation, stylistic errors, and helps fix them before MR is merged. The goals are project-wide consistency of documentation and adherence to the style guides. Docs team introduced a syntax-aware documentation linter for a few repos where you can find vale configuration files. Some contributors write articles without a knowledge of style guides and readability. Refer to the vale linter configuration for CI in the relevant repos:
Documentation linter carries out more than 20 tests:
-
To trigger a CI pipeline to scan for any errors.
-
To lint the words and structure of the documentation.
-
To check the validity of links.
-
To check the readability and run tests for conscious language and more.
Please be aware linter helps you write better, but it does not auto correct errors.
Visuelle Vorschauen
With review apps, a live preview of rendered page is displayed if you click the view app icon or view deployment in preview MR_number.
You will be presented with Artifacts-build page with job number and a link to the rendered page hosted on GitLab. Click the link to inspect the content just like you used to run Docsbuild script in local computer.
Previewing changes during MR review facilitates close collaboration to catch errors and make suggestions to improve content.
The View app button disappears after MR is merged.
Code quality report
To view result of CI linting, go to Pipelines on the left pane and click code quality.
Das Dokumentationsteam wird die Optionen zur systematischen Berücksichtigung von Änderungen auf Basis des Codequalitätsberichts bewerten.
Vielen Dank für Ihre Beiträge.
Want to help? Learn how to contribute to Fedora Docs ›