75 lines
3.2 KiB
Text
75 lines
3.2 KiB
Text
= 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]
|