forked from docs/team-docs
Added 1st cut of Quic Docs contributors guide
This commit is contained in:
Peter Boy
parent
b9ec0471a8
commit
6fab1b0d96
1 changed files with 139 additions and 0 deletions
139
modules/ROOT/pages/contributing-docs/contrib-quickdocs.adoc
Normal file
139
modules/ROOT/pages/contributing-docs/contrib-quickdocs.adoc
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
= Contributing to Quick Docs
|
||||
Peter Boy; Fedora Documentation Team
|
||||
:revnumber: F36 and newer
|
||||
:revdate: 2023-02-07
|
||||
|
||||
|
||||
[abstract]
|
||||
----
|
||||
As a collection of shorter how-tos and more extensive tutorials, the articles cover the entire user-related area of the Fedora Project. We provide some tips and hints on contributing in this special section.
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
**Work in Progress**! Please comment and provide your ideas using the ticket system (rightmost icon below the blue header) or contribute a text using the edit button (second-right below the blue header). Or use the the https://discussion.fedoraproject.org/t/quick-docs-contributors-guide/46584[corresponding discussion thread].
|
||||
====
|
||||
|
||||
== Types of content
|
||||
Fedora Quick Docs is especially a place for 2 types of articles
|
||||
|
||||
How-to::
|
||||
* Intended to be useful when _working_ with Fedora
|
||||
* Characterized by a _strict problem and goal orientation_
|
||||
* It is usually a relativ _short_ text, probably no longer then 60,000 characters.
|
||||
* Comes usually as a _step-by-step_ instruction to resolve a small, specific problem or task, without extensive explanation.
|
||||
Tutorial::
|
||||
* Intended to be useful when _studying_ a software or a set thereof for a specific purpose in Fedora
|
||||
* Characterized by a _learning orientation_
|
||||
* It is often a _more extensiv_ text, probably longer then 80,000 characters.
|
||||
* Comes usually as a _lesson_ type of text, combining some explanations and some step-by-step instructions
|
||||
|
||||
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 FAS account having signed the https://fedoraproject.org/wiki/Legal:Fedora_Project_Contributor_Agreement[Fedora Project Contributor Agreement] (see https://admin.fedoraproject.org/accounts/group/view/cla_done[here]). This is essential for licensing reasons. No other special skills are required.
|
||||
|
||||
Typical roles/tasks are
|
||||
|
||||
* writer
|
||||
* reviewer
|
||||
* spell checking
|
||||
* wording improvements
|
||||
|
||||
|
||||
== How to contribute
|
||||
* Generell a _merge request_ (MR) workflow
|
||||
* Either local authoring environment, GitLab Web IDE, or single page editor
|
||||
|
||||
== What to pay attention to?
|
||||
* Readability (short sentences, structured into short paragraphs. visual guidance / visual structure, no "Pixel Wüste" (pixel desert, don't know the English term for massive, unstructured and therefore just hard to read pile of text)
|
||||
|
||||
|
||||
|
||||
== Article template
|
||||
|
||||
[source,]
|
||||
----
|
||||
= 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:
|
||||
|
||||
// Title::
|
||||
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
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
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. Use this option cautiously and sparingly!
|
||||
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
List is far from complete! TBD: Extend list of 3rd level tags!
|
||||
====
|
||||
|
||||
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue