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

Signed-off-by: Hanku Lee <allegrovelo@gmail.com>

Browse source 
Style guide updated on use of images. A reference to Fedora family products corrected.
This commit is contained in:
hank L 2023-03-11 08:37:12 +00:00
commit 684a1db7fd
No known key found for this signature in database
1 changed files with 17 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,26 +1,26 @@
= Fedora Documentation Style Guide
Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
2023-03-09
2023-03-11
[NOTE]
====
Editors note: This is not yet the final version. Changes can still be introduced in the ongoing discussion.
Editors note: This is a work in progress version. Changes can still be introduced in the ongoing discussion.
====
== Typographic style guide
== Typographic style guide
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
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
* 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 to emphazise text.
Use italics for system objects you mention in a sentence::
+
@ -36,7 +36,7 @@ Use the preformatted source text for command line input or output:: Use a shell
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 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.
== Writing style guide
@ -64,13 +64,13 @@ Use standard US English for spelling and other international differences:: US En
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.
Avoid long, bulky texts:: Such texts are daunting and take time to make sense of.
Avoid long, bulky texts:: Such texts are daunting and take time to make sense of.
+
Instead, organize the text using paragraphs, indentations, or lists. This helps the user to quickly grasp the text and, above all, does not seem daunting.
Instead, organize the text using paragraphs, indentations, or lists. 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.
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.
== Content tips
== 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.
@ -78,9 +78,9 @@ Test your process:: If possible, use a fresh guest VM — or at least a brand-ne
Prefer free software where practical (and officially packaged software wherever possible):: We can 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 good examples.) But we strongly prefer to use FOSS software.
Unless necessary, 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:: We are Fedora. 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_.
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 wherever possible in articles:
+
@ -98,7 +98,7 @@ Use the correct style for third parties:: Names of companies, projects, and tech
== Images and screenshots
Use a fresh, standard Fedora system:: Don't use your personal system or setup. It’s 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 VM with a fresh Fedora variant install, and do the steps there.
Set screen resolution at a reasonable but not too high resolution:: Stay beyond resolutions as 1280x960 or 1280x800.
@ -114,14 +114,14 @@ To follow distinct naming conventions consistently,
Retain the original title of article, use it on a subdirectory name and title of images.
The images go into the directory path ~/modules/ROOT/assets/images/<ARTICLENAME_SHORTEND>/.png
Directory path for images is ~/modules/ROOT/assets/images/<ARTICLENAME_SHORTEND>/.png
.Naming subdirectory and files
[example]
The title on H1 heading is Finding and installing Linux applications. The file name is finding-installing-linux-apps.adoc. Create a subdirectory following paths in Quick Docs repo in Pagure: ~/modules/ROOT/assets/images/finding-installing-linux-apps/.png
If the title on H1 heading is Finding and installing Linux applications, the file name is finding-installing-linux-apps.adoc. Create a subdirectory and place images in following paths in your cloned local repo: ~/modules/ROOT/assets/images/finding-installing-linux-apps/.png
== Processing tips
Check spelling and grammar:: Check your work before creating a Pull Request.
Check the Red Hat style guide:: Use xref:contributing-docs/tools-vale-linter.adoc[Vale] to check your work to make sure it conforms to the Red Hat Style Guide.
Check the Red Hat style guide:: Use xref:contributing-docs/tools-vale-linter.adoc[Vale] to check your work to make sure it conforms to the Red Hat Style Guide.