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

conventions updated for style guide

Browse source
This commit is contained in:
Test Lab 2023-04-03 22:00:19 +00:00 • committed by hankuoffroad
commit 92cda486c9
1 changed files with 32 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

65
modules/ROOT/pages/contributing-docs/style-guide.adoc
View file

@ -1,24 +1,25 @@
= Fedora Documentation Style Guide
Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
2023-04-03
2023-04-04
:page-pagination:
== Writing style guide
Write clearly and use shorter sentences:: Brevity is good. Clarity is better. Don’t be excessively wordy.
Write clearly and use shorter sentences:: The longer a user documentation is, the more difficult it is to understand. Writing with brevity (to the point) is good. Clarity is better.
Avoid passive voice:: Passive voice is the use of the object of a sentence as the subject. For example
* Active voice: The troops defeated the enemy.
* Passive voice: The enemy was defeated by the troops.
Be careful of gerunds (-ing words):: They usually indicate passive voice. Rewrite your sentence to make it stronger. For example:
Be careful of gerunds (-ing):: They indicate passive voice. Rewrite your sentence to make it stronger. For example:
* Weak, passive voice: Setting the foobar configuration option will make the application listen on all interfaces.
* Strong, active voice: Set the foobar configuration option to make the application listen on all interfaces.
Avoid unnecessary future tense:: Unless you’re actually talking about future plans or publications, present tense is best.
Avoid unnecessary future tense:: Unless you are actually talking about future plans or publications, present tense is best.
* Unnecessary future tense: When you select Run, your program will start.
* Present tense: When you select Run, your program starts.
Avoid too much use of the verb to be in sentences:: Too much use of it makes your sentences weak. Try using the verb form of words you’ve shuffled off elsewhere in the sentence. Often you can simply drop words, or use the imperative (commanding or advising) form of the sentence.
Avoid too much use of the verb to be in sentences:: Too much use of *is* makes your sentences weak. Try using the verb form of words you’ve shuffled off elsewhere in the sentence. Often you can simply drop words, or use the imperative (commanding or advising) form of the sentence.
* Weak: Zambone is an app used for managing your private documents on a server.
* Strong: Zambone manages your private documents on a server. Or: Use Zambone to manage your private documents on a server.
* Weak: When setting up a file server, it is important to plan the directory structure carefully.
@ -26,40 +27,36 @@ Avoid too much use of the verb to be in sentences:: Too much use of it makes you
Use standard US English for spelling and other international differences:: US English is the lingua franca for the Fedora Project overall.
Have a smooth flow from general information to specific instructions:: If you’re not sure how to structure your article like this, check out our starter template.
Have a smooth flow from general information to specific instructions:: Structure your article with abstract, bullet points and essential Asciidoc markup.
Avoid long and bulky texts:: Such texts are daunting and take time to make sense of. Instead, organize the text using paragraphs, bullets, and numbered steps. This helps the user to quickly grasp the text and, above all, does not seem daunting. Provide a short abstract at the beginning of a longer collection of paragraphs:: Especially after second and third order headings ("h2" and "h3", "==" and "===" in Asciidoc), a short sentence or paragraph should follow, briefly describing the goal and/or subject of the following paragraphs, i.e. clearly bringing the "message" to the reader's attention and aligning the reader's expectation accordingly.
Avoid long texts:: Verbose writing is daunting to read. Instead, organize the text using paragraphs, bullets, and numbered steps. This helps the user to quickly grasp the text and, above all, does not seem daunting. Provide a short abstract at the beginning of a longer collection of paragraphs:: Especially after second and third order headings ("h2" and "h3", "==" and "===" in Asciidoc), a short sentence or paragraph should follow, briefly describing the goal and/or subject of the subsequent paragraphs, bringing the message to the reader's attention and aligning the reader's expectation.
== Typographic style guide
Use capitalization case for title (h1) and just title:: Capitalize the article title, but just the title.
Use capital case for title (h1) and just title:: Capitalize the article title only.
+
* Incorrect: Fedora documentation style guide
* Correct: Fedora Documentation Style Guide
Use sentence case for the post title and heading titles:: Don’t capitalize words in your article title or any heading, other than proper nouns.
Use sentence case for the post title and heading titles:: Do not capitalize words in your article title or any heading, other than proper nouns.
+
* Incorrect: Technical Notes and Processes
* Correct: Technical notes and processes
Less is more:: Use boldface only for an extremely important phrase or statement. Use italics to emphazise text.
Less is more:: Use boldface only for an extremely important phrase or statement.
Use italics for system objects you mention in a sentence::
+
GUI or CLI elements like button text or menu entries
other prompts the reader must find on the screen commands or package names
Use Italics for system objects mentioned in a sentence:: GUI or CLI elements like button text, menu entries, or prompts the reader find on the screen commands or package names
Use the preformatted source text for command line input or output:: Use a shell prompt ($ or #) to indicate priviledge level and set the input apart from output. It also helps to use boldface for the input itself.
Use the preformatted source text for command line input or output:: Use a shell prompt ($ or #) to indicate privilege level and set the input apart from output.
[source,console]
----
# command arg1 arg2
output line 1
$ command arg1 arg2
output line1
output line2
----
Use Admonitions very sparingly:: They strongly interrupt the reading flow and thus make it difficult to grasp a section of text or even the article as a whole in a meaningful way.
Use of admonitions:: Tips, hints, and Warnings, when used in abundance, interrupt the flow of writing and reading. Use admonitions when absolutely necessary.
== Content tips
@ -67,41 +64,43 @@ These tips are about things to do — and avoid — in what you tell users to do
Test your process:: If possible, use a fresh guest VM — or at least a brand-new user account. Run your process from beginning to end to ensure it works. Fix, rinse, and repeat!
Use free software and officially packaged software:: We could cover non-FOSS software to be used on Fedora, where we know or suspect that software is very popular and useful to Fedora users. Google Chrome or Nvidia driver are an example.
Use free and open source software and officially packaged software:: The article could cover non-FOSS software to be used on Fedora, where there is no alternative FOSS software for Fedora users. Google Chrome or NVIDIA driver are an example.
Use Fedora family distributions:: We are Fedora. Unless your documentation article specifically targets a cross-distribution mechanism, use installations, containers, or distributions within our family (Fedora, CentOS, RHEL).
Use Fedora family distributions:: Unless your documentation article specifically targets a cross-distribution mechanism, use installations, containers, or distributions within our family (Fedora, CentOS, RHEL).
Copr software must be accompanied by a caveat:: The Copr build system is not managed by the Fedora release team and does not provide official software builds. If you cover some software from Copr, ensure there’s no official build. If not, include a statement like this: Copr is not officially supported by Fedora infrastructure. Use packages at your own risk.
Avoid exclusionary or problematic language:: These are examples of terminology to avoid in articles:
Avoid exclusionary language:: These are examples of terminology to avoid in articles:
+
* blacklist/whitelist — Use allowlist/denylist instead, which is more directly descriptive of the purpose.
* master/slave — Use primary/secondary, primary/replica, active/passive, active/standby, or another similar construct.
Use the correct style for third parties:: Names of companies, projects, and technologies do not always follow the style rules of typical English words. Choose the styling used by authoritative websites when you are unsure. If authoritative sources use inconsistent style, use your best judgment. A non-exhaustive list:
* _Copr_ instead of COPR
* _NVIDIA_ instead of Nvidia or nVidia
* _Perl_ instead of PERL
* _Red Hat_ instead of Redhat or RedHat
* _ThinkPad_ instead of Thinkpad
* Copr instead of COPR
* NVIDIA instead of Nvidia or nVidia
* Perl instead of PERL
* Red Hat instead of Redhat or RedHat
* ThinkPad instead of Thinkpad
== Images and screenshots
Use a fresh, standard Fedora system:: Do not use your personal system or setup. It is best to make a VM with a fresh Fedora variant install, and do the steps there.
Use a fresh, standard Fedora system:: Do not use your personal system or setup. It is best to make a virtual machine with a fresh Fedora variant install, and do the steps there.
Set screen resolution at a reasonable but not too high:: Stay beyond resolutions as 1280x960 or 1280x800.
Set screen resolution at a reasonable but not too high:: Desktop environment specific screen capture software produces right-sized images for the articlcs,
If you are only showing a browser window, make it fairly large on the screen and screenshot only the browser:: You can use the screenshot app for this.
If you are showing a browser window, use active window option in screen capture software. Use an option not to include window title bar.
If you are only showing an application, use the default size of the app to screenshot it. Upload and use that original media in your article:: If the shot is large, like a large browser window, app, or whole screen, choose a medium size thumbnail and let Antora CMS handle the conversion.
If you are only showing an application, pop-up, or specific areas, use an option in the software to crop it for you:: If the shot requires an entire browser window, app in full size, or whole screen, choose a medium size thumbnail.
Use descriptions of images prior to block image macro to explain what actions the image display. Check the next page for Asciidoc markup.
=== Use of directory and file naming conventions
To follow distinct naming conventions consistently, retain the original title of article, use it on a subdirectory name and title of images.
To observe naming conventions consistently, retain the original title of article, use it on a subdirectory name and title of images.
Directory path for images is ~/modules/ROOT/assets/images/<ARTICLENAME_SHORTEND>/.png
Directory path for images in Fedora repos follows ~/modules/ROOT/assets/images/<ARTICLENAME_SHORTEND>/.png
.Naming subdirectory and files
[example]