GUIDELINES.adoc

Contributing guidelines

Review the following guidelines when adding a new glossary entry or a new style guideline entry.

Contributing a glossary entry

Use the following template for glossary entries:

AsciiDoc source for a new glossary entry

[[<id>]]
==== <icon> <term> (<class>)
*Description*: <description>

*Use it*: <yes/no/with caution>

[.vale-ignore]
*Incorrect forms*: <incorrect_form>

*See also*: xref:<another_term_id>[<another_term>]

Replace	With	Notes
<id>	The term in lowercase.	If the term consists of more than one word, separate them with a hyphen ("-"). Do not use spaces, capital letters, or special characters (for example, slash "/") in the ID.
<icon>	The appropriate icon related to the "Use it" field.	Possible values: image:images/yes.png[yes] image:images/no.png[no] image:images/caution.png[with caution]
<term>	The term to be described.
<class>	The part of speech of the term.	Possible values: noun, verb, adjective, adverb, pronoun, conjunction, preposition. Use noun for acronyms or abbreviations. Leave the field empty for symbols.
<description>	The description of the term.	Use full sentences with periods. If a term is specific to a particular product, start the description with "In <product_name>,". If a term has multiple meanings, use numbers to separate them. For example: (1) <first_meaning>. (2) <second_meaning>. Add information about why we should or shouldn’t use the term in this form. Alternatively, explain why the terms listed in the Incorrect forms field are incorrect.
<yes/no/with caution>	"yes" if the term should be used. "no" if the term should not be used. "with caution" if the term should be used sporadically or only in certain cases.	Explain why we should or should not use the term in the Description field.
<incorrect_form>	The form of the term that we should not use.	If there are multiple incorrect forms, separate them with a comma (",").
<another_term_id>	The ID of another term related to this one.	Always verify that this ID already exists in the document; otherwise, it will fail to validate if the ID does not exist. Do not include a space between <another_term_id> and [<another_term>].
<another_term>	The term related to this one.	To link to another document or a web page, replace xref:<another_term_id>[<another_term>] with <link>[<name_of_the_document/web_page>].

Additional glossary entry guidelines

• Do not combine two terms into one entry.

• Keep all fields, even if a field is empty. An empty field serves as a placeholder if the field is required later.

• Use quotation marks on first use of a term in the Description field. Do not include an abbreviation in parentheses within the quotation marks; for example, "Asynchronous Transfer Mode" (ATM) is a network technology based on transferring data in cells or packets of a fixed size.

• If the Description field contains more than one paragraph, only the last paragraph is displayed in the Atom linter’s text. Ensure that word usage advice is contained in the last paragraph.

• Use single lines with no breaks for each paragraph. In other words, do not hard wrap at 80 characters, for example.

• If the term has a correct and an incorrect form, always use the correct form instead of <term> and list the incorrect form in the Incorrect forms field. Remember to explain why the incorrect form is incorrect in the Description field.

• If you want to add a term that we should not use and that does not have a correct form, use the incorrect version instead of <term> and add "no" to the Use it field. Explain why we should not use that term in the Description field.

• Creating an ID according to guidance in the template can produce duplicate IDs for distinct entries. For example, the IDs for the "kernel space" and "kernel-space" entries would both be "kernel-space". Similarly, the IDs for the "kB" and "KB" entries would be "kb". Duplicate IDs in a document lead to build errors.

  To avoid this issue, use different IDs:

  • For entries that have different class, append:

    • n for nouns (kernel-space-n)

    • v for verbs

    • adj for adjectives (kernel-space-adj)

    • adv for adverbs

    • conj for conjunctions

    • prep for prepositions

  • For different entries with the same name, for example a command and a program or a programming language of the same name, append command to the command ID, for example ceph-command.

  • For entries that differ in spelling, for example "kB" and "KB", preserve the letter case.

Contributing a style guideline entry

Use the following template when adding a new style guide entry:

AsciiDoc source for a new style entry

[[<id>]]
== <style_item>

<description>

.Example AsciiDoc
----
<example_asciidoc>
----

Replace	With	Notes
<id>	The style item in lowercase.	If the style item consists of more than one word, separate them with a hyphen ("-"). Do not use spaces, capital letters, or special characters (for example, slash "/") in the ID.
<style_item>	The style item to be described.
<description>	The description of the style guidance.	Use full sentences with periods. If applicable, add information about why this guidance is recommended.
<example_asciidoc>	An AsciiDoc example.	Only add an AsciiDoc example if it is applicable to the style guidance.

Additional style entry guidelines

• Do not combine multiple guidelines into one entry.

• Do not add style entries that duplicate guidance already covered by the IBM Style guide.

• Avoid linking to other resources to provide the style guidance. Incorporate the guidance from other resources into the entry description.

• Add the new entry alphabetically in its appropriate category file.

• Use single lines with no breaks for each paragraph. In other words, do not hard wrap at 80 characters, for example.

• Use italics when introducing or defining a term. The following examples demonstrate the use of this guideline:

  • A host group is a group of one or more hosts.

  • Comma-separated values are a set of values in which each value is separated by a comma.

• Use double quotation marks ("") when emphasizing how to write a term. The following examples demonstrate the use of this guideline:

  • Hyphenate "look-up" when using it as a modifier.

  • Write "comma-separated values (CSV)" on first use and "CSV" after that.