Osallistu Docs-artikkelien parantamiseen ja laajentamiseen

Fedora Documentation Team Versio F36 and newer Last review: 2023-05-01

Tässä dokumentissa selitetään, miten Fedora Documentation -verkkosivuston julkaisujärjestelmää käytetään. Se ohjaa sinua osallistumaan olemassa olevaan dokumentaatioon sekä luomaan täysin uusia sisältökokonaisuuksia ja julkaisemaan ne englanninkielisinä alkuperäisinä sekä mahdollisissa käännöksissä.

Fedora-dokumentaatioon voi osallistua monin eri tavoin. Jotkut niistä on suunniteltu mahdollistamaan osallistuminen ilman teknistä osaamista verkkosisällönhallintajärjestelmistä ja siitä, miten panoksesi tallennetaan ja hallitaan. Työkalu hoitaa kaikki nämä ongelmat puolestasi. Se mahdollistaa kirjoittajille keskittymisen käsiteltävään aiheeseen.

Ole hyvä ja tutustu meihin. Jos törmäät dokumentaatiosivuun, joka sisältää virheen tai epätarkkuuden, paranna sivua jollakin alla kuvatuista satunnaisista muokkaustyökaluista. Jos sinulla on kysyttävää, älä epäröi ottaa yhteyttä Docs-tiimiin.

Paikalliset kirjoitustyökalut on suunniteltu tarjoamaan tehokas työympäristö menestyneille kirjoittajille. Ne mahdollistavat tehokkaan työn myös suurissa, monimutkaisissa toisiinsa liittyvissä tekstikokoelmissa. Nämä työkalut on suunnattu kokeneille kirjoittajille.

Kuinka se toimii

Fedora-dokumentaatio käyttää Antoraa verkkosivuston rakentamiseen ja hallintaan. Dokumentaatio on melko staattista sisältöä, ja sitä päivitetään ajoittain. Juuri tähän Antora on erikoistunut. Se kerää staattiset tekstidokumentit ja muuntaa ne kokonaiseksi verkkosivustoksi, mukaan lukien navigointi, linkit, muotoilu, sijoittaminen, mukauttaminen eri lähtölaitteisiin jne. Yleisempää tietoa Antoran julkaisujärjestelmästä löytyy Antoran verkkosivusto ja Antora-dokumentaatio.

Kirjoittajana keskityt sisältöön ja kirjoitat eteenpäin.

Yleinen menettelytapa

4-silmäperiaate pätee Fedora-dokumentaatioon. Eri kirjoittaja arvioi jokaisen panoksen. Kun olet suorittanut tekstin tai tekstin muokkauksen, järjestelmä luo 'Pull Request' tai 'Merge Request' -toiminnon, joka integroi tekstisi dokumentaation runkoon. Tämä saa muut kirjoittajat, hallituksen jäsenet tai kyseisen dokumentaatioelimen osaan sitoutuneet jäsenet aloittamaan tarkastelun ja joko aloittamaan sisällyttämisen tai keskustelun. Anna 2–3 päivää vastaukseen pyyntöön.

Jonkin verran teknistä taustaa

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 to 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 ›