* Write "Ansible." Not "Ansible, Inc." or "AnsibleWorks The only exceptions to this rule are when we're writing legal or financial statements.
* Write "Ansible." Not "Ansible, Inc." or "AnsibleWorks The only exceptions to this rule are when we're writing legal or financial statements.
* Never use the logotype by itself in body text. Always keep the same font you are using the rest of the sentence.
* Never use the logotype by itself in body text. Always keep the same font you are using the rest of the sentence.
@ -15,11 +15,11 @@ Ansible
Capitalization
Capitalization
~~~~~~~~~~~~~~
^^^^^^^^^^^^^^
If it's not a real product, service, or department at Ansible, don't capitalize it. Not even if it seems important. Capitalize only the first letter of the first word in headlines.
If it's not a real product, service, or department at Ansible, don't capitalize it. Not even if it seems important. Capitalize only the first letter of the first word in headlines.
Colon
Colon
~~~~~~~~~~~~~~~~~
^^^^^
A colon is generally used before a list or series:
A colon is generally used before a list or series:
- The Triangle Area consists of three cities: Raleigh, Durham, and Chapel Hill.
- The Triangle Area consists of three cities: Raleigh, Durham, and Chapel Hill.
@ -42,7 +42,7 @@ Use a colon to introduce a bullet list (or dash, or icon/symbol of your choice):
Commas
Commas
~~~~~~~~~~~
^^^^^^
Use serial commas, the comma before the "and" in a series of three or more items:
Use serial commas, the comma before the "and" in a series of three or more items:
- "Item 1, item 2, and item 3."
- "Item 1, item 2, and item 3."
@ -63,11 +63,11 @@ If that does not convince you, maybe this will:
Contractions
Contractions
~~~~~~~~~~~~~
^^^^^^^^^^^^
Do not use contractions in Ansible documents.
Do not use contractions in Ansible documents.
Em dashes
Em dashes
~~~~~~~~~~
^^^^^^^^^
When possible, use em-dashes with no space on either side. When full em-dashes aren't available, use double-dashes with no spaces on either side--like this.
When possible, use em-dashes with no space on either side. When full em-dashes aren't available, use double-dashes with no spaces on either side--like this.
A pair of em dashes can be used in place of commas to enhance readability. Note, however, that dashes are always more emphatic than commas.
A pair of em dashes can be used in place of commas to enhance readability. Note, however, that dashes are always more emphatic than commas.
@ -94,11 +94,11 @@ When used in place of parentheses at the end of a sentence, only a single dash i
Exclamation points (!)
Exclamation points (!)
~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^
Do not use them at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command.
Do not use them at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command.
Gender References
Gender References
~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^
Do not use gender-specific pronouns in documentation. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers."
Do not use gender-specific pronouns in documentation. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers."
It is fine to use "you" when giving instructions and "the user," "new users," and so on. in more general explanations.
It is fine to use "you" when giving instructions and "the user," "new users," and so on. in more general explanations.
@ -109,7 +109,7 @@ Never use "we" when writing. "We" aren't doing anything on the user side. Ansibl
Hyphen
Hyphen
~~~~~~~~~~~~~~
^^^^^^
The hyphen's primary function is the formation of certain compound terms. Do not use a hyphen unless it serves a purpose. If a compound adjective cannot be misread or, as with many psychological terms, its meaning is established, a hyphen is not necessary.
The hyphen's primary function is the formation of certain compound terms. Do not use a hyphen unless it serves a purpose. If a compound adjective cannot be misread or, as with many psychological terms, its meaning is established, a hyphen is not necessary.
Use hyphens to avoid ambiguity or confusion:
Use hyphens to avoid ambiguity or confusion:
@ -136,7 +136,7 @@ In professionally printed material (particularly books, magazines, and newspaper
Lists
Lists
~~~~~~~
^^^^^
Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, and so on.
Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, and so on.
Capitalize the first word of each bullet. Unless it is obvious that it is just a list of items, such as a list of items like:
Capitalize the first word of each bullet. Unless it is obvious that it is just a list of items, such as a list of items like:
@ -153,7 +153,7 @@ When giving instructional steps, use numbered lists instead of bulleted lists.
Months and States
Months and States
~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^
Abbreviate months and states according to AP. Months are only abbreviated if they are used in conjunction with a day. Example: "The President visited in January 1999." or "The President visited Jan. 12."
Abbreviate months and states according to AP. Months are only abbreviated if they are used in conjunction with a day. Example: "The President visited in January 1999." or "The President visited Jan. 12."
Months: Jan., Feb., March, April, May, June, July, Aug., Sept., Nov., Dec.
Months: Jan., Feb., March, April, May, June, July, Aug., Sept., Nov., Dec.
@ -161,17 +161,17 @@ Months: Jan., Feb., March, April, May, June, July, Aug., Sept., Nov., Dec.
Numbers between one and nine are written out. 10 and above are numerals. The exception to this is writing "4 million" or "4 GB." It's also acceptable to use numerals in tables and charts.
Numbers between one and nine are written out. 10 and above are numerals. The exception to this is writing "4 million" or "4 GB." It's also acceptable to use numerals in tables and charts.
Phone Numbers
Phone Numbers
+++++++++++++++
^^^^^^^^^^^^^
Phone number style: 1 (919) 555-0123 x002 and 1 888-GOTTEXT
Phone number style: 1 (919) 555-0123 x002 and 1 888-GOTTEXT
Quotations (Using Quotation Marks and Writing Quotes)
Quotations (Using Quotation Marks and Writing Quotes)
"Place the punctuation inside the quotes," the editor said.
"Place the punctuation inside the quotes," the editor said.
Except in rare instances, use only "said" or "says" because anything else just gets in the way of the quote itself, and also tends to editorialize.
Except in rare instances, use only "said" or "says" because anything else just gets in the way of the quote itself, and also tends to editorialize.
@ -184,7 +184,7 @@ Not:
Semicolon
Semicolon
~~~~~~~~~~~~~~~
^^^^^^^^^
Use a semicolon to separate items in a series if the items contain commas:
Use a semicolon to separate items in a series if the items contain commas:
- Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner.
- Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner.
@ -193,9 +193,9 @@ Use a semicolon before a conjunctive adverb (however, therefore, otherwise, name
Always uppercase. An acronym is a word formed from the initial letters of a name, such as ROM for Read-only memory,
Always uppercase. An acronym is a word formed from the initial letters of a name, such as ROM for Read-only memory,
SaaS for Software as a Service, or by combining initial letters or part of a series of words, such as LILO for LInux
SaaS for Software as a Service, or by combining initial letters or part of a series of words, such as LILO for LInux
@ -11,7 +11,7 @@ LOader.
Spell out the acronym before using it in alone text, such as "The Embedded DevKit (EDK)..."
Spell out the acronym before using it in alone text, such as "The Embedded DevKit (EDK)..."
Applications
Applications
+++++++++++++++++++
^^^^^^^^^^^^
When used as a proper name, use the capitalization of the product, such as GNUPro or Source-Navigator. When used as a command, use lowercase as appropriate, such as "To start GCC, type ``gcc``."
When used as a proper name, use the capitalization of the product, such as GNUPro or Source-Navigator. When used as a command, use lowercase as appropriate, such as "To start GCC, type ``gcc``."
..note::
..note::
@ -19,15 +19,15 @@ When used as a proper name, use the capitalization of the product, such as GNUPr
"vi" is always lowercase.
"vi" is always lowercase.
As
As
++++++++
^^
This is often used to mean "because", but has other connotations, for example, parallel or simultaneous actions. If you mean "because", say "because".
This is often used to mean "because", but has other connotations, for example, parallel or simultaneous actions. If you mean "because", say "because".
Asks for
Asks for
++++++++++++++++
^^^^^^^^
Use "requests" instead.
Use "requests" instead.
Assure/Ensure/Insure
Assure/Ensure/Insure
++++++++++++++++++++++++++++
^^^^^^^^^^^^^^^^^^^^
Assure implies a sort of mental comfort. As in "I assured my husband that I would eventually bring home beer."
Assure implies a sort of mental comfort. As in "I assured my husband that I would eventually bring home beer."
Ensure means "to make sure."
Ensure means "to make sure."
@ -36,292 +36,292 @@ Insure relates to monetary insurance.
Back up
Back up
++++++++++++++
^^^^^^^
This is a verb. You "back up" files; you do not "backup" files.
This is a verb. You "back up" files; you do not "backup" files.
Backup
Backup
++++++++++
^^^^^^
This is a noun. You create "backup" files; you do not create "back up" files.
This is a noun. You create "backup" files; you do not create "back up" files.
Backward
Backward
++++++++++++++
^^^^^^^^
Correct. Avoid using backwards unless you are stating that something has "backwards compatibility."
Correct. Avoid using backwards unless you are stating that something has "backwards compatibility."
Backwards compatibility
Backwards compatibility
++++++++++++++++++++++++
^^^^^^^^^^^^^^^^^^^^^^^
Correct as is.
Correct as is.
By way of
By way of
++++++++++++++++++
^^^^^^^^^
Use "using" instead.
Use "using" instead.
Can/May
Can/May
++++++++++++++
^^^^^^^
Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If either "can," "could," or "may" apply, use "can" because it's less tentative.
Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If either "can," "could," or "may" apply, use "can" because it's less tentative.
CD or cd
CD or cd
+++++++++++++++
^^^^^^^^
When referring to a compact disk, use CD, such as "Insert the CD into the CD-ROM drive." When referring to the change directory command, use cd.
When referring to a compact disk, use CD, such as "Insert the CD into the CD-ROM drive." When referring to the change directory command, use cd.
CD-ROM
CD-ROM
+++++++++++++
^^^^^^
Correct. Do not use "cdrom," "CD-Rom," "CDROM," "cd-rom" or any other variation. When referring to the drive, use CD-ROM drive, such as "Insert the CD into the CD-ROM drive." The plural is "CD-ROMs."
Correct. Do not use "cdrom," "CD-Rom," "CDROM," "cd-rom" or any other variation. When referring to the drive, use CD-ROM drive, such as "Insert the CD into the CD-ROM drive." The plural is "CD-ROMs."
Command line
Command line
+++++++++++++++++++
^^^^^^^^^^^^
Correct. Do not use "command-line" or "commandline" as a noun. If used as an adjective, "command-line" is appropriate, for example "command-line arguments".
Correct. Do not use "command-line" or "commandline" as a noun. If used as an adjective, "command-line" is appropriate, for example "command-line arguments".
Use "command line" to describes where to place options for a command, but not where to type the command. Use "shell prompt" instead to describe where to type commands. The line on the display screen where a command is expected. Generally, the command line is the line that contains the most recently displayed command prompt.
Use "command line" to describes where to place options for a command, but not where to type the command. Use "shell prompt" instead to describe where to type commands. The line on the display screen where a command is expected. Generally, the command line is the line that contains the most recently displayed command prompt.
Daylight saving time (DST)
Daylight saving time (DST)
+++++++++++++++++++++++++++++++
^^^^^^^^^^^^^^^^^^^^^^^^^^
Correct. Do not use daylight savings time. Daylight Saving Time (DST) is often misspelled "Daylight Savings", with an "s" at the end. Other common variations are "Summer Time"and "Daylight-Saving Time". (https://www.timeanddate.com/time/dst/daylight-savings-time.html)
Correct. Do not use daylight savings time. Daylight Saving Time (DST) is often misspelled "Daylight Savings", with an "s" at the end. Other common variations are "Summer Time"and "Daylight-Saving Time". (https://www.timeanddate.com/time/dst/daylight-savings-time.html)
Download
Download
++++++++++++++++
^^^^^^^^
Correct. Do not use "down load" or "down-load."
Correct. Do not use "down load" or "down-load."
e.g.
e.g.
++++++++++
^^^^
Spell it out: "For example."
Spell it out: "For example."
Failover
Failover
+++++++++++++++
^^^^^^^^
When used as a noun, a failover is a backup operation that automatically switches to a standby database, server or network if the primary system fails or is temporarily shut down for servicing. Failover is an important fault tolerance function of mission-critical systems that rely on constant accessibility. Failover automatically and transparently to the user redirects requests from the failed or down system to the backup system that mimics the operations of the primary system.
When used as a noun, a failover is a backup operation that automatically switches to a standby database, server or network if the primary system fails or is temporarily shut down for servicing. Failover is an important fault tolerance function of mission-critical systems that rely on constant accessibility. Failover automatically and transparently to the user redirects requests from the failed or down system to the backup system that mimics the operations of the primary system.
Fail over
Fail over
++++++++++++
^^^^^^^^^
When used as a verb, fail over is two words since there can be different tenses such as failed over.
When used as a verb, fail over is two words since there can be different tenses such as failed over.
Fewer
Fewer
+++++++++++++++++++
^^^^^
Fewer is used with plural nouns. Think things you could count. Time, money, distance, and weight are often listed as exceptions to the traditional "can you count it" rule, often thought of a singular amounts (the work will take less than 5 hours, for example).
Fewer is used with plural nouns. Think things you could count. Time, money, distance, and weight are often listed as exceptions to the traditional "can you count it" rule, often thought of a singular amounts (the work will take less than 5 hours, for example).
File name
File name
+++++++++++++
^^^^^^^^^
Correct. Do not use "filename."
Correct. Do not use "filename."
File system
File system
+++++++++++++++++++
^^^^^^^^^^^
Correct. Do not use "filesystem." The system that an operating system or program uses to organize and keep track of files. For example, a hierarchical file system is one that uses directories to organize files into a tree structure. Although the operating system provides its own file management system, you can buy separate file management systems. These systems interact smoothly with the operating system but provide more features, such as improved backup procedures and stricter file protection.
Correct. Do not use "filesystem." The system that an operating system or program uses to organize and keep track of files. For example, a hierarchical file system is one that uses directories to organize files into a tree structure. Although the operating system provides its own file management system, you can buy separate file management systems. These systems interact smoothly with the operating system but provide more features, such as improved backup procedures and stricter file protection.
For instance
For instance
++++++++++++++
^^^^^^^^^^^^
For example," instead.
For example," instead.
For further/additional/whatever information
For further/additional/whatever information
++++++++++++++++++++++++++++++++++++++++++++++
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use "For more information"
Use "For more information"
For this reason
For this reason
++++++++++++++++++
^^^^^^^^^^^^^^^
Use "therefore".
Use "therefore".
Forward
Forward
++++++++++++++
^^^^^^^
Correct. Avoid using "forwards."
Correct. Avoid using "forwards."
Gigabyte (GB)
Gigabyte (GB)
++++++++++++++
^^^^^^^^^^^^^
2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. Gigabyte is often abbreviated as G or GB.
2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. Gigabyte is often abbreviated as G or GB.
Got
Got
++++++++++++++
^^^
Avoid. Use "must" instead.
Avoid. Use "must" instead.
High-availability
High-availability
++++++++++++++++++
^^^^^^^^^^^^^^^^^
Correct. Do not use "high availability."
Correct. Do not use "high availability."
Highly available
Highly available
++++++++++++++++++
^^^^^^^^^^^^^^^^
Correct. Do not use highly-available."
Correct. Do not use highly-available."
Hostname
Hostname
+++++++++++++++++
^^^^^^^^
Correct. Do not use host name.
Correct. Do not use host name.
i.e.
i.e.
++++++++++++++
^^^^
Spell it out: "That is."
Spell it out: "That is."
Installer
Installer
++++++++++++++
^^^^^^^^^
Avoid. Use "installation program" instead.
Avoid. Use "installation program" instead.
It's and its
It's and its
++++++++++++++
^^^^^^^^^^^^
"It's" is a contraction for "it is;" use "it is" instead of "it's." Use "its" as a possessive pronoun (for example, "the store is known for its low prices").
"It's" is a contraction for "it is;" use "it is" instead of "it's." Use "its" as a possessive pronoun (for example, "the store is known for its low prices").
Less
Less
++++++++++++
^^^^
Less is used with singular nouns. For example "View less details" wouldn't be correct but "View less detail" works. Use fewer when you have plural nouns (things you can count).
Less is used with singular nouns. For example "View less details" wouldn't be correct but "View less detail" works. Use fewer when you have plural nouns (things you can count).
Linux
Linux
++++++++++++++
^^^^^
Correct. Do not use "LINUX" or "linux" unless referring to a command, such as "To start Linux, type linux." Linux is a registered trademark of Linus Torvalds.
Correct. Do not use "LINUX" or "linux" unless referring to a command, such as "To start Linux, type linux." Linux is a registered trademark of Linus Torvalds.
Login
Login
++++++++++++++
^^^^^
A noun used to refer to the login prompt, such as "At the login prompt, enter your username."
A noun used to refer to the login prompt, such as "At the login prompt, enter your username."
Log in
Log in
++++++++++++++
^^^^^^
A verb used to refer to the act of logging in. Do not use "login," "loggin," "logon," and other variants. For example, "When starting your computer, you are requested to log in..."
A verb used to refer to the act of logging in. Do not use "login," "loggin," "logon," and other variants. For example, "When starting your computer, you are requested to log in..."
Log on
Log on
++++++++++++++
^^^^^^
To make a computer system or network recognize you so that you can begin a computer session. Most personal computers have no log-on procedure -- you just turn the machine on and begin working. For larger systems and networks, however, you usually need to enter a username and password before the computer system will allow you to execute programs.
To make a computer system or network recognize you so that you can begin a computer session. Most personal computers have no log-on procedure -- you just turn the machine on and begin working. For larger systems and networks, however, you usually need to enter a username and password before the computer system will allow you to execute programs.
Lots of
Lots of
++++++++++++++
^^^^^^^
Use "Several" or something equivalent instead.
Use "Several" or something equivalent instead.
Make sure
Make sure
++++++++++++++
^^^^^^^^^
This means "be careful to remember, attend to, or find out something." For example, "...make sure that the rhedk group is listed in the output."
This means "be careful to remember, attend to, or find out something." For example, "...make sure that the rhedk group is listed in the output."
Try to use verify or ensure instead.
Try to use verify or ensure instead.
Manual/man page
Manual/man page
++++++++++++++++++
^^^^^^^^^^^^^^^
Correct. Two words. Do not use "manpage"
Correct. Two words. Do not use "manpage"
MB
MB
++++++++
^^
(1) When spelled MB, short for megabyte (1,000,000 or 1,048,576 bytes, depending on the context).
(1) When spelled MB, short for megabyte (1,000,000 or 1,048,576 bytes, depending on the context).
(2) When spelled Mb, short for megabit.
(2) When spelled Mb, short for megabit.
MBps
MBps
++++++++++++++
^^^^
Short for megabytes per second, a measure of data transfer speed. Mass storage devices are generally measured in MBps.
Short for megabytes per second, a measure of data transfer speed. Mass storage devices are generally measured in MBps.
MySQL
MySQL
++++++++++++++
^^^^^
Common open source database server and client package. Do not use "MYSQL" or "mySQL."
Common open source database server and client package. Do not use "MYSQL" or "mySQL."
Need to
Need to
++++++++++++++
^^^^^^^
Avoid. Use "must" instead.
Avoid. Use "must" instead.
Read-only
Read-only
++++++++++++
^^^^^^^^^
Correct. Use when referring to the access permissions of files or directories.
Correct. Use when referring to the access permissions of files or directories.
Real time/real-time
Real time/real-time
++++++++++++++++++++++
^^^^^^^^^^^^^^^^^^^
Depends. If used as a noun, it is the actual time during which something takes place. For example, "The computer may partly analyze the data in real time (as it comes in) -- R. H. March." If used as an adjective, "real-time" is appropriate. For example, "XEmacs is a self-documenting, customizable, extensible, real-time display editor."
Depends. If used as a noun, it is the actual time during which something takes place. For example, "The computer may partly analyze the data in real time (as it comes in) -- R. H. March." If used as an adjective, "real-time" is appropriate. For example, "XEmacs is a self-documenting, customizable, extensible, real-time display editor."
Refer to
Refer to
++++++++++++++
^^^^^^^^
Use to indicate a reference (within a manual or website) or a cross-reference (to another manual or documentation source).
Use to indicate a reference (within a manual or website) or a cross-reference (to another manual or documentation source).
See
See
++++++++++++++
^^^
Don't use. Use "Refer to" instead.
Don't use. Use "Refer to" instead.
Since
Since
++++++++
^^^^^
This is often used to mean "because", but "since" has connotations of time, so be careful. If you mean "because", say "because".
This is often used to mean "because", but "since" has connotations of time, so be careful. If you mean "because", say "because".
Tells
Tells
++++++++++++++
^^^^^
Use "Instructs" instead.
Use "Instructs" instead.
That/which
That/which
++++++++++++++
^^^^^^^^^^
"That" introduces a restrictive clause-a clause that must be there for the sentence to make sense. A restrictive clause often defines the noun or phrase preceding it. "Which" introduces a non-restrictive, parenthetical clause-a clause that could be omitted without affecting the meaning of the sentence. For example: The car was travelling at a speed that would endanger lives. The car, which was traveling at a speed that would endanger lives, swerved onto the sidewalk. Use "who" or "whom," rather than "that" or "which," when referring to a person.
"That" introduces a restrictive clause-a clause that must be there for the sentence to make sense. A restrictive clause often defines the noun or phrase preceding it. "Which" introduces a non-restrictive, parenthetical clause-a clause that could be omitted without affecting the meaning of the sentence. For example: The car was travelling at a speed that would endanger lives. The car, which was traveling at a speed that would endanger lives, swerved onto the sidewalk. Use "who" or "whom," rather than "that" or "which," when referring to a person.
Then/than
Then/than
++++++++++++++
^^^^^^^^^
"Then" refers to a time in the past or the next step in a sequence. "Than" is used for comparisons.
"Then" refers to a time in the past or the next step in a sequence. "Than" is used for comparisons.
..image:: images/thenvsthan.jpg
..image:: images/thenvsthan.jpg
Third-party
Third-party
++++++++++++++
^^^^^^^^^^^
Correct. Do not use "third party".
Correct. Do not use "third party".
Troubleshoot
Troubleshoot
++++++++++++++
^^^^^^^^^^^^
Correct. Do not use "trouble shoot" or "trouble-shoot." To isolate the source of a problem and fix it. In the case of computer systems, the term troubleshoot is usually used when the problem is suspected to be hardware -related. If the problem is known to be in software, the term debug is more commonly used.
Correct. Do not use "trouble shoot" or "trouble-shoot." To isolate the source of a problem and fix it. In the case of computer systems, the term troubleshoot is usually used when the problem is suspected to be hardware -related. If the problem is known to be in software, the term debug is more commonly used.
UK
UK
++++++++++++++
^^
Correct as is, no periods.
Correct as is, no periods.
UNIX®
UNIX®
++++++++++++++
^^^^^
Correct. Do not use "Unix" or "unix." UNIX® is a registered trademark of The Open Group.
Correct. Do not use "Unix" or "unix." UNIX® is a registered trademark of The Open Group.
Unset
Unset
++++++++++++++
^^^^^
Don't use. Use Clear.
Don't use. Use Clear.
US
US
++++++++++++++
^^
Correct as is, no periods.
Correct as is, no periods.
User
User
++++++++++++++
^^^^
When referring to the reader, use "you" instead of "user." For example, "The user must..." is incorrect. Use "You must..." instead. If referring to more than one user, calling the collection "users" is acceptable, such as "Other users may wish to access your database."
When referring to the reader, use "you" instead of "user." For example, "The user must..." is incorrect. Use "You must..." instead. If referring to more than one user, calling the collection "users" is acceptable, such as "Other users may wish to access your database."
Username
Username
++++++++++++++
^^^^^^^^
Correct. Do not use "user name."
Correct. Do not use "user name."
View
View
++++++++++++++
^^^^
When using as a reference ("View the documentation available online."), do not use View. Use "Refer to" instead.
When using as a reference ("View the documentation available online."), do not use View. Use "Refer to" instead.
Within
Within
++++++++++++++
^^^^^^
Don't use to refer to a file that exists in a directory. Use "In".
Don't use to refer to a file that exists in a directory. Use "In".
World Wide Web
World Wide Web
++++++++++++++
^^^^^^^^^^^^^^
Correct. Capitalize each word. Abbreviate as "WWW" or "Web."
Correct. Capitalize each word. Abbreviate as "WWW" or "Web."
Webpage
Webpage
++++++++++++++
^^^^^^^
Correct. Do not use "web page" or "Web page."
Correct. Do not use "web page" or "Web page."
Web server
Web server
++++++++++++++
^^^^^^^^^^
Correct. Do not use "webserver". For example, "The Apache HTTP Server is the default Web server..."
Correct. Do not use "webserver". For example, "The Apache HTTP Server is the default Web server..."
Website
Website
++++++++++++++
^^^^^^^
Correct. Do not use "web site" or "Web site." For example, "The Ansible website contains ..."
Correct. Do not use "web site" or "Web site." For example, "The Ansible website contains ..."
Who/whom
Who/whom
++++++++++++++
^^^^^^^^
Use the pronoun "who" as a subject. Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition. For example: Who owns this? To whom does this belong?
Use the pronoun "who" as a subject. Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition. For example: Who owns this? To whom does this belong?
Will
Will
++++++++++++++
^^^^
Do not use future tense unless it is absolutely necessary. For instance, do not use the sentence, "The next section will describe the process in more detail." Instead, use the sentence, "The next section describes the process in more detail."
Do not use future tense unless it is absolutely necessary. For instance, do not use the sentence, "The next section will describe the process in more detail." Instead, use the sentence, "The next section describes the process in more detail."
Wish
Wish
++++++++++++++
^^^^
Use "need" instead of "desire" and "wish." Use "want" when the reader's actions are optional (that is, they may not "need" something but may still "want" something).
Use "need" instead of "desire" and "wish." Use "want" when the reader's actions are optional (that is, they may not "need" something but may still "want" something).
x86
x86
++++++++++++++
^^^
Correct. Do not capitalize the "x."
Correct. Do not capitalize the "x."
x86_64
x86_64
++++++++++++++
^^^^^^
Do not use. Do not use "Hammer". Always use "AMD64 and Intel® EM64T" when referring to this architecture.
Do not use. Do not use "Hammer". Always use "AMD64 and Intel® EM64T" when referring to this architecture.
You
You
++++++++++++++
^^^
Correct. Do not use "I," "he," or "she."
Correct. Do not use "I," "he," or "she."
You may
You may
++++++++++++++
^^^^^^^
Try to avoid using this. For example, "you may" can be eliminated from this sentence "You may double-click on the desktop..."
Try to avoid using this. For example, "you may" can be eliminated from this sentence "You may double-click on the desktop..."
Why is it important to use the TM, SM, and ® for our registered marks?
Why is it important to use the TM, SM, and ® for our registered marks?
Before a trademark is registered with the United States Patent and Trademark Office it is appropriate to use the TM or SM symbol depending whether the product is for goods or services. It is important to use the TM or SM as it is notification to the public that Ansible claims rights to the mark even though it has not yet been registered.
Before a trademark is registered with the United States Patent and Trademark Office it is appropriate to use the TM or SM symbol depending whether the product is for goods or services. It is important to use the TM or SM as it is notification to the public that Ansible claims rights to the mark even though it has not yet been registered.
@ -8,7 +8,7 @@ Before a trademark is registered with the United States Patent and Trademark Off
Once the trademark is registered, it is appropriate to use the symbol in place of the TM or SM. The symbol designation must be used in conjunction with the trademark if Ansible is to fully protect its rights. If we don't protect these marks, we run the risk of losing them in the way of Aspirin or Trampoline or Escalator.
Once the trademark is registered, it is appropriate to use the symbol in place of the TM or SM. The symbol designation must be used in conjunction with the trademark if Ansible is to fully protect its rights. If we don't protect these marks, we run the risk of losing them in the way of Aspirin or Trampoline or Escalator.
General Rules:
General Rules:
+++++++++++++++
^^^^^^^^^^^^^^
Trademarks should be used on 1st references on a page or within a section.
Trademarks should be used on 1st references on a page or within a section.
@ -29,7 +29,7 @@ Also add the trademark disclaimer.
- [Name of Trademark] is a registered trademark and [Name of Trademark] is a trademark of Red Hat, Inc. in the United States and other countries.
- [Name of Trademark] is a registered trademark and [Name of Trademark] is a trademark of Red Hat, Inc. in the United States and other countries.
Guidelines for the proper use of trademarks:
Guidelines for the proper use of trademarks:
+++++++++++++++++++++++++++++++++++++++++++++
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Always distinguish trademarks from surround text with at least initial capital letters or in all capital letters.
Always distinguish trademarks from surround text with at least initial capital letters or in all capital letters.
@ -72,18 +72,18 @@ Never alter a trademark in any way including through unapproved fonts or visual
Never abbreviate or use any Ansible trademarks as an acronym.
Never abbreviate or use any Ansible trademarks as an acronym.
The importance of Ansible trademarks
The importance of Ansible trademarks
++++++++++++++++++++++++++++++++++++++++++++++++
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Ansible trademark and the "A" logo in a shaded circle are our most valuable assets. The value of these trademarks encompass the Ansible Brand. Effective trademark use is more than just a name, it defines the level of quality the customer will receive and it ties a product or service to a corporate image. A trademark may serve as the basis for many of our everyday decisions and choices. The Ansible Brand is about how we treat customers and each other. In order to continue to build a stronger more valuable Brand we must use it in a clear and consistent manner.
The Ansible trademark and the "A" logo in a shaded circle are our most valuable assets. The value of these trademarks encompass the Ansible Brand. Effective trademark use is more than just a name, it defines the level of quality the customer will receive and it ties a product or service to a corporate image. A trademark may serve as the basis for many of our everyday decisions and choices. The Ansible Brand is about how we treat customers and each other. In order to continue to build a stronger more valuable Brand we must use it in a clear and consistent manner.
The mark consists of the letter "A" in a shaded circle. As of 5/11/15, this was a pending trademark (registration in process).
The mark consists of the letter "A" in a shaded circle. As of 5/11/15, this was a pending trademark (registration in process).
Common Ansible Trademarks
Common Ansible Trademarks
+++++++++++++++++++++++++++++++++++++++
^^^^^^^^^^^^^^^^^^^^^^^^^
* Ansible®
* Ansible®
Other Common Trademarks and Resource Sites:
Other Common Trademarks and Resource Sites:
++++++++++++++++++++++++++++++++++++++++++++++++
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Linux is a registered trademark of Linus Torvalds.
- Linux is a registered trademark of Linus Torvalds.
- UNIX® is a registered trademark of The Open Group.
- UNIX® is a registered trademark of The Open Group.
- Microsoft, Windows, Vista, XP, and NT are registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/en-us.aspx
- Microsoft, Windows, Vista, XP, and NT are registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/en-us.aspx
The essence of the Ansible writing style is short sentences that flow naturally together. Mix up sentence structures. Vary sentence subjects. Address the reader directly. Ask a question. And when the reader adjusts to the pace of shorter sentences, write a longer one.
The essence of the Ansible writing style is short sentences that flow naturally together. Mix up sentence structures. Vary sentence subjects. Address the reader directly. Ask a question. And when the reader adjusts to the pace of shorter sentences, write a longer one.
- Write how real people speak...
- Write how real people speak...
@ -15,6 +15,6 @@ The essence of the Ansible writing style is short sentences that flow naturally
- When possible, start task-oriented sentences (those that direct a user to do something) with action words. For example: Find software... Contact support... Install the media.... and so forth.
- When possible, start task-oriented sentences (those that direct a user to do something) with action words. For example: Find software... Contact support... Install the media.... and so forth.
Active Voice
Active Voice
------------------
------------
Use the active voice ("Start Linuxconf by typing...") rather than passive ("Linuxconf can be started by typing...") whenever possible. Active voice makes for more lively, interesting reading.
Use the active voice ("Start Linuxconf by typing...") rather than passive ("Linuxconf can be started by typing...") whenever possible. Active voice makes for more lively, interesting reading.
Also avoid future tense (or using the term "will") whenever possible For example, future tense ("The screen will display...") does not read as well as an active voice ("The screen displays"). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system.
Also avoid future tense (or using the term "will") whenever possible For example, future tense ("The screen will display...") does not read as well as an active voice ("The screen displays"). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system.
Aine Riordan
3 years ago
committed by