# General Style Rules

The following Style Rules provide guidelines for general documentation style choices.

Capitalization in Hyphenated Words in Titles
  Description: This rule defines how to capitalize hyphenated words in titles.

  Rule: Always capitalize the first letter of the first word before the hyphen (regardless of the type of word or its length). For the subsequent words, consider them separate words and follow the same rules as forTitles/Headings.

Capitalization in Titles/Headings
  Description: These rules are meant to define how to capitalize words in titles and headings in our documentation.

  Rules: Follow these style rules for the User Guide:

  - Capitalize the first letter of the first word, regardless of the number of letters or type of word.
  - Capitalize the first letter of all nouns.
  - Capitalize the first letter of all verbs.
  - Capitalize all letters of acronyms, unless the common naming convention for a specific acronym dictates otherwise (for example, "HiDPI").
  - Capitalize the first letter of all other words that have at least 4 letters, with the exception of the prepositions and conjunctions listed below.
  - DO NOT capitalize the prepositions "from", "like", "into", "over", "with", or the conjunction "that".
  - DO NOT capitalize words with 3 or fewer letters (except for nouns, verbs, and the first word), including the following words: "a", "an", "and", "as", "at", "but", "by", "for", "in", "it", "of", "nor", "on", "or", "the", "to", "up".
  - DO NOT capitalize specific names of code components (such as the names of elements, attributes, etc.) Use proper tags (`codeph`) for them, even in titles.
  - When listing company names or products in titles, use the same capitalization format that they use.
Company or Product Names
  Description: This rule defines how to write company and product names.

  Rule: When listing company names or products, use the same capitalization format and naming convention that the company uses (for example, "oXygen" or "XProc").

Icons
  Description: These rules are meant as a guideline when listing interface icons for actions (such as toolbar and menu actions).

  Rules: Follow these style rules for the User Guide:

  - Whenever listing an action that has an icon on the toolbar or in a menu, include an image of the icon before the name of the action.
  - When using icons before the name of an action, do not add a space between the icon and the action name.
  - Put both the icon and the name of the action inside a `uicontrol`.
  - Whenever possible, use a maximum height of 16 pixels.
  - Avoid using layers, transparency, or other metadata.
  - Use a white background.
  - Use PNG for the format. When using GIMP, deselect all of the save as options.
Images
  Description: These rules are meant as a guideline when using images in the documentation.

  Rules: Follow these style rules for the User Guide:

  - Generally, it is best to only include images to supplement the content and provide some sort of useful context for the reader. For example, it is not necessary to include images for features or dialog boxes that are self explanatory.
  - Unless the image is very small and appears in the middle of a block of text, it is always best to include the image in a `fig` element and include a title.
  - The maximum height and width is 650 pixels, but it is always best to make the images as small as possible without sacrificing resolution.
  - Use a white background.
  - Use PNG for the format. When using GIMP, deselect all of the save as options.
Links
  Description: It is better to include more links than what is necessary, rather than leaving your readers without the means for easily navigating to other pertinent content.

  Rules: Provide links whenever more clarification could be helpful. The types of things that should be linked include:

  - Pronouns and other specific terms that may not be common knowledge. Glossary terms should be used in many of these cases.
  - When listing a specific option (such as options in a Preference page, specific dialog box, menu, etc.) a link should be included to reference the specific topic that describes the option.
  - Whenever referring to certain specifications or other external resources, provide links to those specific resources.
  - Use cross references to other topics that have more information about specific ideas.
  - Use related links to other topics that include similar information about the current topic.
Lists
  Description: The various types of lists are indented differently in the output and therefore certain list types look better in particular situations. These rules are meant to define what type of lists to use in certain situations.

  Rules: Use the following guidelines for the type of lists to use in the User Guide:

  - The most important rule to follow is that you should always consider the most commonly used output format and try to provide a visually appealing contrast for lists. You do not want your readers to become discouraged with a seemingly never ending wall of unordered lists (or other types of lists, one after another).
  - When describing actions or options (for example, the topics that describe the preference pages), it is better to use definition lists (`dl`), especially for parent nodes. Unordered lists (`ul`) can be used in the `dd` elements for lists inside the definition lists to provide contrast.
  - When documenting procedural information, use unordered lists (`ul`) when steps do not need to occur in sequence.
  - When documenting procedural information, always use ordered lists (`ol`) when the steps must occur in a sequence.
Notes
  Description: These rules are meant to define when and how to use note elements.

  Rules: Follow these style rules in regards to notes in the User Guide:

  - If possible, avoid adding consecutive notes.
  - If necessary to add consecutive notes, then use different types.
  - Add a note when:
    - You want to emphasize something important.
    - The idea does not fit with the flow of the section.
Parentheses
  Description: These rules are meant to define when and how to use parentheses.

  Rules: Parentheses can be used to set apart additional information that is useful to the reader but not integral to the rest of the sentence. Follow these style rules for the User Guide:

  - When using them in normal writing (as opposed to some sort of code), use parentheses (brackets) instead of square brackets, hyphens, semicolons, or any other symbol.
  - Typically, you should place text that is surrounded by parentheses inside a sentence, rather than as a sentence of its own. In most instance in our documentation, if it is a complete sentence of its own, the content should not be in parentheses.
  - Whatever is inside the parentheses, it must not be grammatically integral to the surrounding sentence. If it is, the sentence must be rewritten.
  - Follow the punctuation inside parentheses rules.
Possession
  Description: Normally, in English writing, you indicate possession for a singular noun with an apostrophe plus the letter "s". It can be a bit complicated when dealing with nouns that end in an "s" (plural or singular) and it can sometimes lead to confusion. However, in technical writing, it is better to avoid using possession to avoid any possibility of confusion. In most instances, there is an alternate way of writing sentences that might include words that show possession. While these alternate ways might sometimes seem overly formal for general writing or spoken communication, in technical writing, not only are they acceptable, but they are actually preferred because the more formal ways of writing the sentences are usually considered to be more professional and more grammatically correct.

  Rule: Avoid using possessives in the User Guide, if at all possible. If you find yourself using an apostrophe to show possession, rewrite the sentence. There might be some rare cases where you cannot find a better ways of writing the sentence and in those cases, use an apostrophe plus "s" at the end of singular nouns and just an apostrophe at the end of words that end in "s" (plural or singular).

Plural Acronyms
  Description: These rules define how to list plural acronyms. This is a difficult one to define because there are a lot of different opinions about it among experts and there does not seem to be a consensus for how they should be written. The problem is that there are a variety of ways that acronyms are read and deciphered and there is a lot of different opinions about which method looks the best and which methods cause the most ambiguity. The rules that were chosen are meant to make it as simple as possible while avoiding as much ambiguity as possible.

  Rules: Follow these style rules for the User Guide:

  - DO NOT use 's at the end of acronyms since apostrophes are meant to denote possession. Since we try to avoid using possession, and hence apostrophes, in our documentation, we certainly do not want to cause confusion by using them to signify a plural acronym.
  - To prevent any type of confusion, if at all possible, try to avoid using plural acronyms entirely. Try to find a way to write the sentence in singular form or expand the acronym to its full name.
  - If you do need to use a plural acronym, capitalize all letters of the actual acronym and then use a lower case s at the end. If it seems to look odd, use italics for the s. This also applies to acronyms that end in an S (for example, CMSs).
Punctuation in Lists or Steps
  Description: These rules define how to use punctuation at the end of lists or steps.

  Rules: Follow these style rules for the User Guide:

  - DO NOT use semi-colons at the end of list items or steps.
  - Be consistent with the ending punctuation for all items (bullets) within a list or step.
  - Use a period at the end of the list items or steps, or a colon if introducing another list inside the list item or step.
  - If each bullet only contains one word (or a series of proper nouns), punctuation is not necessary and usually looks better without.
Spelling: American vs. British English
  Description: There are some words that are spelled differently in these two forms of English (for example, "color" in American English vs. "colour" in British English). It is certainly grammatically acceptable to use either convention as long as you are consistent. This rule is meant to define which convention we should use for such words in our documentation.

  Rule: Since we have more customers in North America than in Great Britain, we will always use American English spelling for our documentation.

Structured Markup
  Description: It is important to use markup liberally and consistently to make the documentation more visually appealing and readable. These rules are meant to be general guideline for using tags consistently throughout the documentation.

  Rules: The following list is just some of the most common tags that are used in the User Guide, and a description of the type of content that should be placed in the tags.

  - API Names (`apiname`) - Use this tag for specific names of API extensions, methods, and classes.
  - Bold (`b`) - Use this tag to provide an emphasis on certain text.
  - Code Phrases (`codeph`) - Use this tag for the specific names of elements, attributes, and other snippets of code.
  - File Paths (`filepath`) - Use this tag for listing the name of a specific file or file path.
  - Italic (`i`) - Use this tag for content that should stand out from normal text.
  - Keyboard Shortcuts (`shortcut`) - Use this tag to identify keyboard shortcuts.
  - Notes (`note`) - Use this tag for drawing attention to additional information beyond the main text. Use the `type` attribute to differentiate multiple contiguous notes or to define their importance.
  - Oxygen (`product`) - Use the `product` key whenever referring to oXygen.
  - Terms (`term`) - Use this tag for glossary terms and other words or phrases that the reader might want an additional explanation or definition.
  - UI Controls (`uicontrol`) - Use this tag for specific names of user interface items, such as names of buttons, actions, dialog boxes, views, menus, and modes (Text, Author, Grid, or Design). Alternatively, `wintitle` can be used for names of such things as dialog boxes, views, modes, or windows since `uicontrol` and `wintitle` tags are rendered the same in all the outputs.
  - WebApp (`webappProduct`) - Use the `webappProduct` code template whenever referring to WebApp (the product or component).
    Tip: It is useful to transform individual topics into XHTML to see how the use of tags will look in the output.
Writing Approach for Creating Topics
  Description: These rules are meant to provide basic guidelines for the type of approach that should be used for creating topics in the User Guide.
  Rules: Follow these rules for creating topics in the User Guide:
  - Each topic should be based on a single overall idea.
  - Each topic should be complete in and of itself, while linking to other related and relevant information.
  - Each topic should be able to stand on its own without requiring the user to read other topics prior to the current one.
  - Regardless of how the topics are organized the map, users should be able to read them in any order and skip around to other topics without a required sequence. However, topics should also be arranged in a logical order in the map or table of contents so that users can navigate in a logical sequence, if they so desire.
  - Each topic should be designed so that it makes sense if readers find it with the first result from a search.
    Tip: Consider the following example. This was originally the first sentence in a topic about custom XML refactoring operations: If none of the predefined operations will help you accomplish a particular refactoring task, you can create a custom operation that is specific to your needs. If this was the first topic they came across in a specific search, they may question what "predefined operations" the topic is referring to, especially since there was no link to the predefined operations. Accordingly, it is better to begin the topic with this sentence: While oXygen XML Editor includes a variety of predefined XML refactoring operations to help you accomplish particular tasks, you can also create custom operations according to your specific needs.