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

external contributor workflow test without FAS. removed italic when not necessary

Browse source
This commit is contained in:
Test Lab 2023-02-24 23:54:56 +00:00
commit 66de74b80a
1 changed files with 16 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,6 +1,6 @@
= Fedora Documentation Style Guide
Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
v0.0.1, 2022-09-26
2023-02-24
[NOTE]
====
@ -12,13 +12,13 @@ Editors note: This is not yet the final version. Changes can still be introduced
Use capitalization case for title (h1) and just title:: Capitalize the article title, but just the title.
+
* _Incorrect_: Fedora documentation style guide
* _Correct_: Fedora Documentation Style Guide
* 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.
+
* _Incorrect_: Technical Notes and Processes
* _Correct_: Technical notes and processes
* 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.
@ -29,7 +29,7 @@ Use italics for system objects you mention in a sentence::
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.
[source,]
[source]
----
# command arg1 arg2
output line 1
@ -43,22 +43,22 @@ Use Admonitions very sparingly:: They strongly interrupt the reading flow and th
Write clearly and use shorter sentences:: Brevity is good. Clarity is better. Don’t be excessively wordy when avoidable. If a longer sentence is easier to read, use the extra words.
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.
* 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:
* _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.
* 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.
* _Unnecessary future tense_: When you select Run, your program will start.
* _Present tense_: When you select Run, your program starts.
* 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 is, will be, or can be makes your sentences weak and flabby. 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.
* _Strong_: Plan the directory structure of the file server carefully before you set it up.
* 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.
* Strong: Plan the directory structure of the file server carefully before you set it up.
Use standard US English for spelling and other international differences:: US English is the lingua franca for the Fedora Project overall.