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 käyttää AsciiDoc-tyyliä tekstin muotoiluun yksinkertaisella ja tehokkaalla tavalla. Se noudattaa tarkasti luonnollisia kirjoitustyylejä jokapäiväisissä muistiinpanoissa jäsentämisessä ja korostamisessa. Tällä tavoin voit käyttää mitä tahansa editoria, mukaan lukien lähes mitä tahansa tekstinkäsittelyohjelmaa, joka voi muokata ja tallentaa AsciiDoc-tekstiä. Lisätietoja tästä alla.

AsciiDoc-tekstidokumentti tallennetaan useisiin Git-arkistoon. Tämä järjestelmä on erityisen suosittu ohjelmistokehittäjien keskuudessa, mutta se soveltuu myös erittäin hyvin tekstidokumenttien hallintaan. Git kannustaa ja helpottaa neljän silmän periaatteen käyttöä "veto- (tai yhdistämis-) pyyntötyönkulun" avulla. Sinun tarvitsee huolehtia tämän työnkulun yksityiskohdista vain, jos haluat luoda paikallisen työympäristön, joka on tarkoitettu ammattimaiseen ja säännölliseen osallistumiseen. Kaikki muut työkalut hoitavat tarvittavat vaiheet taustalla.

Edellytykset

Fedora-dokumentaatioon osallistumisen ainoat vaatimukset ovat:

Työkalut

Nopea tapa: Muokkaa-painike

  • Tee pieniä korjauksia yksittäiseen tiedostoon suoraan Git Forgen verkkokäyttöliittymästä.

  • Kirjoitusoikeudet ylävirran repositorioon vaaditaan.

  • Käytä sitä poikkeuksena (ilman tarkistusprosessia), eikä suositeltuna vaihtoehtona.

Helppo tapa: Git Forgen Web IDE

  • Tee muutoksia useisiin tiedostoihin suoraan Git Forgen verkkokäyttöliittymästä.

  • Ei tarvitse asentaa mitään paikalliseen tietokoneeseen tai ajaa Git-komentoja terminaalissa.

  • Tarkistuspyynnöt (Merge Requests in GitLab)

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

Joustava ja edistynyt tapa: Luo paikallinen kirjoitusympäristö

  • Työskentele useiden tiedostojen ja repojen kanssa offline-tilassa omaan tahtiin, käyttäen valitsemaasi tekstieditoria ja terminaalia.

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

Tyypillisiä tapoja osallistua

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 ›