Osallistuminen Quick Docsiin

Hanku Lee, Peter Boy, Fedoran dokumentaatiotiimi Last review: 2023-03-19
Quick Docs on kokoelma lyhyempiä oppaita ja laajempia opetusohjelmia Fedora Linuxin käyttäjille. Annamme vinkkejä ja vinkkejä Quick Docsiin osallistumiseen.

Sisältötyypit

Fedora Quick Docs koostuu kahdentyyppisistä artikkeleista.

Kuinka tehdä ohjeet

Sen ominaisuudet ovat

  • Tarkoitettu hyödylliseksi Fedoran kanssa työskennellessä

  • Ongelma- ja tavoitesuuntautuminen

  • Se on yleensä suhteellisen lyhyt, enintään 60 000 merkkiä pitkä

  • Se tulee yleensä vaiheittaisena ohjeena pienen, tarkan ongelman tai tehtävän ratkaisemiseksi ilman laajaa selitystä

Tutoriaali

Sen ominaisuudet ovat

  • Tarkoitettu hyödylliseksi tutkittaessa ohjelmistoa tai sen joukkoa tiettyyn tarkoitukseen Fedorassa

  • Characterized by learning new skills

  • It is often a more extensive text longer than 80,000 characters

  • Ensure comprehension of the features followed by walkthroughs of a software program

If your post does not fit into either category, consider an article under Administration Tools or on the Home page. The best place to ask is discussion.fedoraproject.org #docs.

Who can contribute

Everyone can contribute and everyone is welcome! There are some minor and easy to meet requirements, though. The most important is a Fedora account having signed the Fedora Project Contributor Agreement. This is essential to protect Fedora from any potential licensing issues. Of course, some knowledge of the AsciiDOC markup language is helpful, but you can get along very well without it. This is especially true when correcting and revising existing articles. One can easily get into the existing flow.

An important fact is, no special knowledge is required! You don’t need to know anything about desktop publishing, complicated formatting tricks or anything like that.

The range of feasible and needed contributions is wide. Everyone can contribute an important element. Typical roles/tasks are;

  • writer

  • technical reviewer

  • spell checking

  • wording improvements

  • QuickDoc organization

  • revision of the articles

Tehtävien löytäminen

Whether it is broken link, outdated screenshots of graphical user interface, technical and grammatical error, every little contribution, no matter how small, helps Fedora Linux users.

While reading an article

The greatest opportunity to contribute comes from reading an article itself. Whenever you come across an error, an omission or unclear wording, you can contribute an improvement in passing. In the header of each article are links to 2 of the 3 tools for contributions.

easy contrib
Kuva 1. Links to contributing tools

The rightmost button leads to a ticket system where you can point out the problem.

report issue
Kuva 2. Point out blunders you found

The subject field already contains a link to the affected document. Don’t change it. Please, provide a description of the issue and if possible provide a concise suggested modification, preferably cut&paste ready.

If you are not logged to pagure, a FAS login window will open first.

The second link opens a web editor, you can use to enter proposed modifications directly in the text.

report issue
Kuva 3. The web editor

The next steps are explained in detail in the article How to edit files on the Pagure Web UI.

Itsemääräiset ongelmat

You can find and contribute to needed changes by following the Quick Docs Issue Board, where users share blunders in the documentation or suggestions for enhancing it.

Jos löydät asian, joka vastaa kiinnostusta ja asiantuntemustasi, oikealla yläkulmassa olevasta assignee-kohdasta paina take-linkkiä ja osoita asian itsellesi.

assign issues
Kuva 4. Assign issues

Kuinka osallistua

Quick Docs uses the same CMS as all other Fedora Docs, so the tools are the same. You find detailed guides in the section Contribution Tools.

Pull-pyynnöt ja arvostelu

In either case, the workflow follows the "pull request" or "merge request" model. Changes are not made in the existing, published text but in a side version. When the work is complete, a "merge request" is triggered. Members of the community will look at the changes and either start a discussion or accept the changes. They will then be merged into the published version. We thus follow the 4-eyes principle.

Pull Requestit edistävät yhteistyötä kirjoittajien ja arvioijien välillä, ja PR-kommentit, muokkaukset ja sitoumukset toimivat arviointiprosessina.

The individual steps are largely automatic. Details are described in the respective tools.

IlmoitusPR jälkeen

You probably want to track the further progress after the PR. That’s what the Watch function is for.

Pikadokumenttiraportin keskellä olevassa kellotilassa on neljä vaihtoehtoa. Valitse yksi vaihtoehdoista alta.

  • Katso anti ja PR

  • Katso kommentit

  • Katso anti, PR ja kommentit

  • Ei katsottu

Ilmoitus menee sähköpostiisi, kuten Paguren käyttäjäasetuksissa.

watch notification
Kuva 5. Ilmoituksen asetukset

Jos et kuule arvioijilta PR:n jälkeen yli viikkoa, jätä kommentti PR-osioon seurataksesi asiaa.

What to pay attention to

Readability

  • Write short sentences, structured into short paragraphs. Avoid the wall of text when creating content.

  • Use clear structure and minimal formatting for better reading flow

Adherence to style guide

Instead of nitpicking consistency of tone and grammatical errors, reviewers encourage writers to read The docs style guide. If you want automated test, run vale linter locally Check Your Documentation Using Vale.

Sääntöjoukot

Tyyliohjeen lisäksi tässä on muutama sääntö, joita tekijöiden tulee noudattaa.

  • Prosessidokumentaatiotiimi käsittelee virheitä dokumentaatiossa samalla periaatteella kuin koodivirheet, joissa otetaan käyttöön jatkuva integraatio, automaattinen testaus ja asteittaiset parannukset dokumentaation laadun parantamiseksi.

  • Kaikki muutokset Quick Docsiin on tehtävä haarautuneen projektin pull-pyyntöjen kautta. Quick Docs -projekti ei tue suoraa push-ohjelmaa ylävirran repoon.

  • Jos korjaat sisältöä uusista ominaisuuksista, julkaisuista tai uudesta sisällöstä, testaa sovellusta ja prosessia uudessa järjestelmässä tai vastikään asennetussa virtuaalikoneessa, johon kaikki päivitykset on asennettu.

  • Älä käytä terminaalin kuvakaappauksia. Tarjoa tietyn kielen lähdekoodilohko tai kuorikomento.

  • Aja proosalinteriä kuten Vale paikallisesti ennen PR:ää. Katso tämä linkki: Kuinka tarkistaa dokumentaatiotyyli Valen avulla

Article template

= ARTIKKELIN_OTSIKKO
AUTHOR_1; AUTHOR_2; AUTHOR_3 :revnumber: Fxy :revdate: yyyy-mm-dd :category: CATEGORY :tags: TAG_01 TAG_02 TAG_03 ... TAG_n //:page-aliases: OPTIONAL

// Optional free form useful additional information as comment


[abstract] Mission statement of 2-3 sentences

Notes:

Authors line

We would like to list the last 3 authors who worked on the article in terms of substance and content. Of coure, any contribution is welcome! But at this prominent position we do not want to include minor changes, such as spelling mistakes or individual wording corrections.

Alternatively use The Fedora Documentation Team

revnumber

Use the release number preceded by 'F', e.g. F37, or a range of releases, e.g. F36,F37,F38 or F33-F37. Be as specific as possible and use 'all' only in exceptional cases

revdate

The last date someone checked the content for category:: Select only one category from below. A category is mandatory! Categories (and tags) are the only way to retrieve an atricle.

tags

one or more tags from list below

abstract

1-3 sentences describing content and goal. Avoid any redundancy, e.g. repeating the title

You can also download the template to make it easier.

List of categories to choose from

You can select only one category!

  • Administration

  • Installation

  • Managing software

  • Upgrading

List is far from complete! TBD: Extend list of categories

List of tags to choose from

You can select multipe tags!

  • 1st level tags, choose at least one:

    • How-to

    • Tutorial

  • 2nd level tags, choose multiple, none if system wide

    • Workstation

      • Gnome

      • KDE

      • XFCE

    • Silverblue

    • Kinoite

    • Server

    • CoreOS

    • IoT

  • 3rd level tags, optional, choose multiple

    • Problem-solving / Troubleshooting

    • Printing / Scanning

    • SELinux

You are free to choose additional 3rd level tag(s) if none fits your contribution.

Docs-tiimi tarvitsee apuasi

Auta meitä ongelmissa, PR:issä, uusien kirjoittajien perehdyttämisessä tai artikkelivaraston pitämisessä ajan tasalla. Kiitos!

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