= 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 and web links.  Match the capitalization of
  the button or link text.
* 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.  Mark it bold in paths (`*<install-dir>*/examples`) to
  highlight its special meaning.
* Use `<broker-instance-dir>` to refer the location of the user's
  broker instance.
* Use `<install-dir>` for the component install directory.
* Don't use contractions, ;).
* Use `++_yay_++` for emphasis, not `++*yay*++`.
* Use `[discrete]` for unnumbered titled sections.  Don't 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 small integers - "four", not "4" - all the way up to nine.
* Use "e.g.", not "eg".  Consider using "for example"
  instead.  Note that you almost always want to follow either
  expression with a comma.
* Use "i.e.", not "ie".  Consider using "that is" instead, and these
  also will want a comma.
* Niggles
** Don't use "&" in place of "and".
** Don't use "and/or".  Pick one.
** The words "server" and "broker" are not capitalized unless they
   begin a sentence or appear in a title.
** Use "heartbeating", not "heart-beating".
** Avoid the word "simply" unless it clarifies.
** Use "etc.", not "etc".

== 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]