Contribuire a migliorare e ampliare gli articoli della documentazione

Team di Documentazione di Fedora https://discussion.fedoraproject.org/tag/docs Version F36 and newer Last review: 2023-05-01

Questo documento spiega come utilizzare il sistema di pubblicazione impiegato per realizzare il sito web della documentazione di Fedora. Ti guiderà sia nel contribuire alla documentazione esistente, sia nel creare nuovi contenuti completi e pubblicarli nelle versioni originali in inglese, oltre che nelle eventuali traduzioni.

Ci sono molti modi diverse per contribuire alla documentazione di Fedora. Alcuni di essi sono pensati per permettere contributi senza la necessità di conoscenze tecniche sui sistemi di gestione dei contributi web e su come archiviare e gestire il proprio contributo. Lo strumento si occupa di tutte queste questioni per te, permettendo agli autori di concentrarsi sull’argomento trattato.

Per favore dacci un’occhiata. Se ti capita di trovare una pagina di documentazione che contiene un errore o un’informazione inesatta, usa uno degli strumenti di contributo informali descritti qui sotto per migliorare la pagina. Se hai domande, non esitare a contattare il team della documentazione.

Gli strumenti di scrittura locale sono progettati per offrire un ambiente di lavoro potente ad autori esperti. Permettono di lavorare in modo efficiente anche su raccolte di testi grandi, complesse e interconnesse. Questi strumenti sono destinati ad autori con esperienza.

How it works

Fedora documentation uses Antora to build and manage the Web site. Documentation is fairly static content, with occasional updates from time to time. This is exactly what Antora specializes in. It gathers static text documents and transforms them into a complete Web site, including navigation, links, formatting, positioning, adaptation to different output devices, etc. For more general information about the Antora publishing system, see the Antora website and Antora documentation.

As a writer, you concentrate on the content and write away.

The general procedure

The 4-eyes principle applies to the Fedora documentation. A different author reviews each contribution. When you complete your text or text modification, the system creates a "Pull Request" or "Merge Request" to integrate your text into the documentation body. This triggers other authors, board members or members committed to the part of the documentation body in question, to start a review and either initiates an inclusion or starts a discussion. Allow 2 to 3 days for an answer to a request.

Some technical background

Fedora uses AsciiDoc to format text in a simple and efficient way. It closely follows natural writing styles in everyday notes for structuring and highlighting. In this way, you can use any editor, including almost any word processor that can edit and save AsciiDoc Text. More about this below.

The AsciiDoc text document is stored in a series of Git repositories. This is a system especially popular among software developers, but also very capable for managing text documents. Git encourages and facilitates the use of the 4-eyes principle by a "Pull (or Merge) Request Workflow". You only need to worry about the details of this workflow if you want to set up a local work environment intended for professional and frequent contributions. All other tools take care of the necessary steps in the background.

Prerequisites

The only requirements for contributing documentation to Fedora Docs are:

The tools

Quick way: 'Edit' button

  • Make changes to a single file for minor fixes directly from web UI of Git forge.

  • Write access to upstream repo required.

  • Use it as an exception (without review process), rather than a recommended option.

Easy way: Web IDE of Git forge

  • Make changes to multiple files directly from web UI of Git forge.

  • No need to install anything in local computer or run Git commands in terminal.

  • Pull Requests for review process (Merge Requests in GitLab)

  • You do not need special permissions or write access to the original project.

Flexible and advanced way: Create a local writing environment

  • Work with multiple files and repos offline at your pace using your choice of text editor and terminal.

  • You can build and render the pages locally to test your changes using Podman container.

Typical ways to contribute

One can distinguish several typical types of contribution to Fedora documentation, for which the available tools are suitable in different ways.

There are many ways for various types of contribution. For example, typo fixes, adding short information or a link, update an article, write a new article.

Update an existing documentation page

This task involves minor changes. For example, typo fixes, adding short information or a link, or a correction to the text. This type is especially necessary whenever the documentation needs to be updated for a new software version.

The File Edit button are convenient for this purpose.

Extend an existing documentation domain

This task involves adding one or more new chapter(s) or section(s) with several chapters. For example, adding another container technique to the documentation of containerization.

The Web IDE is a convenient tool for this purpose. A local writing environment is useable as well, but may involve too much overhead if you want contribute to just one document.

It is highly recommended to present the plan on one of the Docs communication channels before starting. You may get suggestions and tips on content, but also on editing. For example, file structure and naming conventions.

Introduce a new documentation area

This task involves a new extensive subject area, such as new software or a new administration tool. For example, inclusion of several sections and chapters and the creation of a new, separate repository.

For this type, setting up a local writing environment is useful and worthwhile.

In any case, a prior discussion with the Docs team is necessary, if only to create the technical prerequisites.

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