Contributing to Quick Docs

Peter Boy, Hanku Lee, Fedora Documentation Team Last review: 2023-03-19
This article is an introduction to Quick Docs, which is a collection of shorter how-to guide and more extensive tutorials for users of the Fedora Linux. We provide some tips and hints on contributing to Quick Docs.

Types of content

Fedora Quick Docs consists of two types of articles.

How-to guide

Its characteristics are

  • Intended to be useful when working with Fedora

  • Problem and goal orientated

  • It is usually a relatively short text no longer than 60,000 characters

  • Comes usually as a step-by-step instruction to resolve a small, specific problem or task, without extensive explanation

Tutorial

Its characteristics are;

  • Intended to be useful when studying a software or a set thereof for a specific purpose in Fedora

  • 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! The only requirement is a Fedora account having signed the Fedora Project Contributor Agreement (see here). This is essential for licensing reasons. No other special skills are required.

Typical roles/tasks are;

  • writer

  • technical reviewer

  • spell checking

  • wording improvements

  • QuickDoc organization

  • revision of the articles

How to contribute

  • General Pull Requests (PR) workflow

  • Either local authoring environment or page editor in Pagure user interface

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.

Workflow

Experienced writers are more than welcome to customize workflow to suit their needs. If you are not sure of where to start, visit How to contribute to Quick Docs repo.

Article template

= ARTICLE_TITLE
AUTHOR_1; AUTHOR_2; AUTHOR_3
:revnumber: Fxy
:revdate: yyyy-mm-dd

// Optional  free form useful additional information as comment

:category: CATEGORY
:tags: TAG_01 TAG_02 TAG_03 ... TAG_n

[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

rev_number

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

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.

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