Kuinka käyttää GitLab-käyttöliittymää monimutkaisempaan asiakirjojen ylläpitoon
Dokumentaatiota pitää ylläpitää sisällön kasvaessa. Kirjoittajat ja arvioijat voivat osallistua dokumentaatioihin helposti ja tehokkaasti GitLabin verkkokäyttöliittymässä. Web IDE:stä, CI-putkistosta renderöidyn sisällön yhteisarviointiin ja sivujen hyväksyntään voit työskennellä hyvän sisällön ja dokumenttien ylläpidon parissa ilman keskeytyksiä asennukseen ja konfigurointiin. Artikkeli olettaa, että olet jo perehtynyt Gitin ja jatkuvan integraation (CI) kanssa.
Asiakirjojen ylläpito
Dokumentaation ylläpito ilmenee monin tavoin.
-
Tekninen tarkkuus
-
Up-to-dateness
-
Dokumentaation kuratointi loogisessa järjestyksessä
-
Johdonmukaisuus esityksessä
-
Vakiomallipohjat, attribuutit ja käytännöt, joita sovelletaan Docs-repoissa
-
CI-putken käyttö dokumenttien laadun tarkistusten automatisointiin
Seuraavat osiot käyvät läpi, miten ylläpitää ja jatkuvasti parantaa Fedora Docs -repositioita GitLabin sisäänrakennettujen työkalujen avulla.
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.
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.
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.
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.
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.
Want to help? Learn how to contribute to Fedora Docs ›