Bijdragen aan documentatie voor Weblate

U bent van harte uitgenodigd om elke door u gekozen pagina van de documentatie verbeteren. Doe dat gemakkelijk door te klikken op de knop Edit this page in de rechterbovenhoek van de pagina.

Documentatie richtlijnen

Respecteer deze richtlijnen tijdens het schrijven:

  1. Verwijder geen deel van de documentatie als dat nog geldig is.

  2. Gebruik duidelijke en gemakkelijk te begrijpen taal. U schrijft technische documenten, geen gedicht. Niet alle lezers van de documentatie zijn sprekers in de eigen taal, denk daar aan.

  3. Wees niet bang om het te vragen als u niet zeker bent van uw zaak. Als u iets na moet vragen over een bepaalde mogelijkheid tijdens het bewerken, wijzig dan de documenten ervan niet voordat u het antwoord heeft. Dit betekent: U vraagt of u wijzigt. Doe niet allebei tegelijkertijd.

  4. Verifieer uw wijzigingen door de beschreven acties uit te voeren, terwijl u de documentatie volgt.

  5. Verstuur een PR met wijzigingen in kleine delen om het gemakkelijker en sneller te kunnen beoordelen en samen te voegen.

  6. Als u opnieuw wilt schrijven en de structuur van een groot artikel wilt wijzigen, doe dat dan in twee stappen:

    1. Opnieuw schrijven

    2. Als het opnieuw geschreven deel eenmaal is beoordeeld, gepolijst en samengevoegd, wijzig dan de structuur van de alinea’s in een ander PR.

De documentatie lokaal bouwen

Documentation can be also edited and built locally, the Python requirements are in the docs dependency group in pyproject.toml. If you already use the full development environment, uv sync --all-extras --dev is enough. For documentation work only, uv sync --group docs is sufficient.

The recommended local workflow is:

make -C docs update-docs
./ci/run-docs

The ci/run-docs wrapper builds the documentation with warnings treated as errors.

Hint

U zult ook graphviz geïnstalleerd moeten hebben om de documentatie te bouwen.

De documentatie vertalen

U kunt de documentatie vertalen.

Updating generated documentation snippets

Several documentation sections use templates generated from the code. The preferred way to refresh them is:

make -C docs update-docs

This target regenerates the snippets currently used by the documentation, including:

  • add-on events, built-in add-ons, and common add-on parameters

  • machine translation services

  • file format parameters and file format feature tables

  • permissions and built-in roles

  • checks and check flags

Keep manually maintained text in the parent documentation page rather than adding it to autogenerated snippets. For example, Add-ons includes three generated files for events, built-in add-ons, and common add-on parameters, while obsolete add-ons are maintained directly in the page.

If you need to regenerate only one part, the individual management commands are documented in Opdrachten voor beheer, and the exact commands used by update-docs are listed in docs/Makefile.