Bug 1033855

Summary: Conventions.xml contains words that violate the style guide
Product: [Community] Publican Reporter: Matthew Casperson <mcaspers>
Component: publicanAssignee: PnT DevOps Devs <hss-ied-bugs>
Status: CLOSED NOTABUG QA Contact: tools-bugs <tools-bugs>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 3.2CC: aigao, cbredesen, rlandman
Target Milestone: ---   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2013-11-24 22:31:38 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description Matthew Casperson 2013-11-23 20:18:42 UTC 
"This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles." 

This sentence contains the word sub-menu. According to the style guide, the correct spelling is "submenu".

---

"To connect to a remote machine using ssh, type ssh username at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john." 

This sentence contains the word "username" to describe a users credentials. According to the style guide, "user name" is to be used when describing credentials, and "username" is to be used when describing a variable.

---

"Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration." 

This sentence contains the word the word "may". According the the style guide, "may" is to be used only to describe situations where permission is being given. If either "can," "could," or "may" apply, use "can" - it is less tentative.

---

"Warnings should not be ignored." 

This sentence contains the word "should". According to the style guide, "should" needs to be replaced with "must". For example, "You should make a backup" is a suggestion, while "You must make a backup" is a requirement.
Comment 2 Matthew Casperson 2013-11-23 23:06:51 UTC 
"Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system."

This sentence contains the word "enter". According to the style guide, when referring to typing a command, "type" should be used instead, such as "To open Source-Navigator from the command line, type snavigator."
Comment 3 Matthew Casperson 2013-11-23 23:08:45 UTC 
"It will return a result as follows: package-version-release."

This sentence contains the word "will". According to the style guide, future tense is not to be used unless it is absolutely necessary. For example, do not write "The next section will describe the process in detail." Instead, write "The next section describes the process in detail."
Comment 4 Matthew Casperson 2013-11-23 23:10:45 UTC 
"If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold."

This sentence contains the word "will". See the previous comment for the style guides rule on the word "will".
Comment 5 Matthew Casperson 2013-11-23 23:13:02 UTC 
"The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context."

"The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context."

These sentences contains the word "above". According to the style guide, "above" is not to be used to use to refer to information mentioned previously. Use a cross-reference instead.
Comment 6 Matthew Casperson 2013-11-23 23:13:43 UTC 
"If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold."

This sentence contains the word above. See the previous comment for the style guides rule on the word "above".
Comment 7 Matthew Casperson 2013-11-23 23:59:20 UTC 
"Fill out the following template in Bugzilla's Description field. Be as specific as possible when describing the issue; this will help ensure that we can fix it quickly."

This sentence contains the word "will".
Comment 8 Jeff Fearn 🐞 2013-11-24 22:31:38 UTC 
Publican is subject to this style guide. If you feel the need to match a style guide then your brand is the correct place to do it.
Comment 9 Jeff Fearn 🐞 2013-11-24 22:32:00 UTC 
Publican is _not_ subject ...