mwinters/docs-team-docs
1
0
Fork 0
forked from docs/team-docs
Code Pull requests Activity

Quick Docs contribution updated

Browse source
This commit is contained in:
hank L 2023-03-19 15:35:53 +00:00
commit d7b9f2dc4b
1 changed files with 46 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

93
modules/ROOT/pages/contributing-docs/contrib-quickdocs.adoc
View file

@ -1,62 +1,73 @@
= Contributing to Quick Docs
Peter Boy; Fedora Documentation Team
:revnumber: F36 and newer
Peter Boy; Hanku Lee; Fedora Documentation Team
:revdate: 2023-03-19
[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].
====
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 is especially a place for two types of articles
How-to::
Its characteristics are
* Intended to be useful when working with Fedora
* Characterized by a strict problem and goal orientation
* It is usually a relatively short text, probably 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
Fedora Quick Docs consists of two types of articles.
=== How-to guide
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 orientation
* It is often a more extensive text, probably longer than 80,000 characters
* Comes usually as lesson type of text, combining some explanations and some step-by-step instructions
- Intended to be useful when working with Fedora
- Problem and goal orientated
- It is usually a relatively short text, probably 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 orientation
- It is often a more extensive text, probably longer than 80,000 characters
- A combination of some explanations followed by 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
Everyone can contribute and everyone is welcome! The only requirement is a Fedora 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.
* writer
* technical reviewer
* spell checking
* wording improvements
* QuickDoc organization
* Revision of the articles
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
- 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. Use visual guidance and visual structure. Avoid the wall of text when creating content.
* Adherence to style guide: Refer to xref:contributing-docs/style-guide.adoc
=== 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 xref:contributing-docs/style-guide.adoc#prerequisites[The docs style guide]. If you want automated test, run vale linter locally xref:contributing-docs/tools-vale-linter.adoc#prerequisites[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 xref:contributing-docs/contributions-quick-repo.adoc#prerequisites[How to contribute to Quick Docs repo].
== Article template
[source,]
[source]
----
= ARTICLE_TITLE
AUTHOR_1; AUTHOR_2; AUTHOR_3
@ -112,7 +123,6 @@ You can select __multipe tags__!
** How-to
** Tutorial
* 2nd level tags, choose multiple, none if system wide
** Workstation
*** Gnome
@ -130,13 +140,4 @@ You can select __multipe tags__!
** 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!
====
You are free to choose additional 3rd level tag(s) if none fits your contribution.