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

Paragraph aligned and trademark AsciiDoc corrected

Browse source
This commit is contained in:
hank L 2023-04-04 18:48:41 +00:00
commit 8e321e508c
1 changed files with 8 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -11,7 +11,7 @@ Avoid passive voice:: Passive voice is the use of the object of a sentence as th
* Active voice: The troops defeated the enemy.
* Passive voice: The enemy was defeated by the troops.
Be careful of gerunds (-ing):: They 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 sound strong. 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.
@ -27,9 +27,9 @@ Avoid too much use of the verb to be in sentences:: Too much use of *is* makes y
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:: Structure your article with abstract, bullet points and essential Asciidoc markup.
Have a smooth flow from general information to specific instructions:: Structure your article with abstract, bullet points and essential AsciiDoc markup.
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.
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
@ -56,15 +56,15 @@ Use the preformatted source text for command line input or output:: Use a shell
output line2
----
Use of admonitions:: Tips, hints, and Warnings, when used in abundance, interrupt the flow of writing and reading. Use admonitions when absolutely necessary.
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
These tips are about things to do — and avoid — in what you tell users to do. Remember that thousands of readers trust Fedora Documentation to tell them how to carry out tasks. Be responsible and helpful, test your examples carefully, advocate best practices, and respect the user’s security and choice.
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!
Test your process:: If possible, use a fresh guest virtual machine — 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 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 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.
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).
@ -88,13 +88,9 @@ Use the correct style for third parties:: Names of companies, projects, and tech
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:: Desktop environment specific screen capture software produces right-sized images for the articlcs,
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 showing a browser window, use active window option in screen capture software. Use an option not to include window title bar.
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, 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.
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