2017-03-30 16:44:54 +00:00
= 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]
2017-03-30 20:06:50 +00:00
* link:terms_conventions.adoc[RH-SSO Terms and Conventions]
2017-03-30 16:44:54 +00:00
* 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]