= Documentation Style Guide

== Style Guides to Follow

. IBM Style Guide (printed)
. link:https://www.ibm.com/developerworks/library/styleguidelines/[IBM DeveloperWorks Editorial Style Guide]
. link:http://brand.redhat.com/elements/[RH Corporate]
. This document

== Style Guidelines

* Use title case for headings
** Unsure of the proper capitalization? See link:http://titlecase.com/[http://titlecase.com/]  
* Keep headings inside their associated topic file rather than
  outside, at the site of the include.
* Use `++[[this_style_of_thing]]++` for document IDs, not
  `++[[this-style]]++` or `++[[ThisStyle]]++`.
* Use `ThisStyle` for custom attributes, not `this-style` or
  `this_style`.
* Use `this-style` (all lower case) for file and directory names,
  not `this_style`, or `ThisStyle`.
* Use `++`backticks`++` for filesystem names and paths, symbols,
  and literals.
* Use *bold* for GUI items.  Match the capitalization of
  the button.
* Stick to one file per chapter unless the content is too long,
  excluding reusable topics.
* Use gerunds not imperatives for chapter and topic titles -
  "configuring", not "configure".
* Terminate bulleted and numbered lists with periods unless the items
  listed are simple names.
* Use `$ sudo`, not `#` for superuser console commands.
* Use `++`__SOME_VAR__`++` for placeholders in filesystem 
  paths or console output. (For example : `__INSTALL_DIR__`/examples)
* Don't use contractions, ;).
* Use `++_yay_++` for emphasis, not `++*yay*++`.
* Use `[discrete]` for unnumbered titled sections.  Do not use `.Some
  Title` for this.
* Use title case for table and block titles (`.Example Title of Note`).
** Unsure of the proper capitalization? See link:http://titlecase.com/[http://titlecase.com/]
* Use "zip", not ".zip" or "ZIP".  The same goes for tar.
* Document IDs are book-scoped, so they don't need the book title in
  them.
* Refer to the top-level sections of books as chapters, not sections
  or topics.
* Spell out integers that are less than 10 - "four", not "4".
** Always use numerals in ranges, even when either or both of the numbers are less than 10.
* Do not use Latin abbreviations, such as e.g., etc., and i.e.
** Instead of etc. use "and so on" when you list a clear sequence of elements, such as "1, 2, 3, and
so on".  Otherwise, rewrite the sentence to replace etc. with something more descriptive, 
such as "and other output."
** Instead of i.e. use "that is".
** Instead of e.g. use "for example".
* Niggles
** Do not use "&" in place of "and".
** Do not use "and/or".  Pick one.
** Use "heartbeating", not "heart-beating".
** Avoid the word "simply" unless it clarifies.

== Tips

* For substitution of `{attr}` in code blocks, use `[subs=+attributes]`.
* For styling of `++*bold*++` (`*bold*`) in code blocks, use
  `[subs=+quotes]`.
== See Also

* link:screenshots.adoc[Screenshot Guide]
* link:terms_conventions.adoc[RH-SSO Terms and Conventions]
* link:http://ccs-jenkins.gsslab.brq.redhat.com:8080/job/glossary-of-terms-and-conventions-for-product-documentation-branch-master/lastSuccessfulBuild/artifact/index.html[Red Hat Glossary of Terms and Conventions]
. link:https://mojo.redhat.com/docs/DOC-1136272[Red Hat Style Guide and Writers Checklist]