Come usare l’interfaccia di GitLab per una manutenzione più approfondita della documentazione

Team di Documentazione di Fedora https://discussion.fedoraproject.org/tag/docs Last review: 2023-05-13

La documentazione necessita di manutenzione man mano che il contenuto cresce. Autori e revisori possono contribuire facilmente ed efficacemente alla documentazione all’interno dell’interfaccia web di GitLab. Dall’IDE web, alla pipeline CI, fino alla revisione collaborativa dei contenuti web renderizzati e all’approvazione delle pagine, puoi lavorare su contenuti di qualità e sulla manutenzione della documentazione senza interruzioni dovute a installazioni o configurazioni. L’articolo presuppone che tu abbia già familiarità con Git e l’integrazione continua (CI).

Manutenzione della documentazione

La manutenzione della documentazione assume molte forme.

Precisione tecnica
Up-to-dateness
Curation of documentation in a logical order
Coerenza nella presentazione
Standard template, attributes and conventions applied throughout Docs repos
Use of CI pipeline to automate docs quality checks

The following sections step through how to maintain and continually improve quality of Fedora Docs repos using built-in tools in GitLab.

GitLab Web IDE

Launched as part of the GitLab 15.7 release in December 2022, the new Web IDE provides a file explorer, a text editor and source control in one place.

Explorer

The explorer on the left pane helps to discover the repository structure and file list in Fedora Docs. Whichever repos, standard repository structure allows contributors to navigate files and cross-reference multiple pages quickly.

Figure 1. Explorer

Text editor

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.

Figure 2. View a list of changed files

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.

Figure 3. Write, commit, create MR

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.

Visual reviews

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.

Figure 4. Live preview using view app

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.

Figure 5. MR preview in deployment

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.

Figure 6. View result of CI linting

Docs team will evaluate options to reflect changes systematically based on code quality report.

Thanks for your contributions.

Want to help? Learn how to contribute to Fedora Docs ›