Merge pull request #238 from matthewhelmke/styleupdates

Edited existing style guide for usefulness

internal_resources/contributing.adoc

@@ -31,17 +31,22 @@ You only need to perform these tasks once, when preparing to contribute.
 . Fork the link:https://github.com/keycloak/keycloak-documentation[Keycloak documentation repository]. This will create your own version of the repository which you can find at `https://github.com/{yourusername}/keycloak-documentation` where `{yourusername}` is the username you created in GitHub.
 . Install `git` on your local machine. The procedure differs by operating system as described in link:https://git-scm.com/book/en/v2/Getting-Started-Installing-Git[Installing Git]. Follow up with initial Git setup tasks, as described in link:https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup[First Time Git Setup].
 . Clone from your fork to create a copy on your local machine and then navigate to the new directory by entering the following from the command line on your local machine:
++
 [source,bash]
 ----
 $ git clone https://github.com/{yourusername}/keycloak-documentation
 $ cd keycloak-documentation
 ----
++
 . Add a git remote to your local repository to link to the upstream version of the documentation. This makes it easier to update your fork and local version of the documentation.
++
 [source,bash]
 ----
 $ git remote add upstream https://github.com/keycloak/keycloak-documentation
 ----
++
 . Check your settings.
++
 [source,bash]
 ----
 $ git remote -v
@@ -50,6 +55,7 @@ origin	https://github.com/{yourusername}/keycloak-documentation.git (push)
 upstream	https://github.com/keycloak/keycloak-documentation (fetch)
 upstream	https://github.com/keycloak/keycloak-documentation (push)
 ----
++
 
 NOTE: It is possible to clone using SSH so you don't have to enter a username/password every time you push. Find instructions at link:https://help.github.com/articles/connecting-to-github-with-ssh/[Connecting to GitHub with SSH] and link:https://help.github.com/articles/which-remote-url-should-i-use/[Which Remote URL Should I Use]. When using SSH, the origin lines will appear like this:
 `git@github.com:{yourusername}/keycloak-documentation.git`

internal_resources/styleguide.adoc

@@ -3,68 +3,50 @@
 == Style Guides to Follow
 
 . IBM Style Guide (printed)
+. This document
+
+Writers will also refer to these:
 . 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
+* 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
+* Write clear, short sentences.
-  outside, at the site of the include.
+* Use definite and indefinite articles like _an_ and _the_.
-* Use `++[[this_style_of_thing]]++` for document IDs, not
++
-  `++[[this-style]]++` or `++[[ThisStyle]]++`.
+*Incorrect:* Create project. Delete object from editor. +
-* Use `ThisStyle` for custom attributes, not `this-style` or
+*Correct:* Create a project. Delete an object from the editor.
-  `this_style`.
++
-* Use `this-style` (all lower case) for file and directory names,
+* Start steps with an active verb, such as *Enter*, *Edit*, and *Click*.
-  not `this_style`, or `ThisStyle`.
+* Start headings with gerunds (verbs that end in -ing), such as *Configuring*, *Creating*, and *Installing*.
-* Use `++`backticks`++` for filesystem names and paths, symbols,
+* Use *bold* for GUI items. Match the capitalization you see in the GUI.
-  and literals.
+* End entries in bulleted and numbered lists with periods when the entries are complete sentences.
-* Use *bold* for GUI items.  Match the capitalization of
+* Use `$ sudo`, not `#` for superuser terminal commands.
-  the button.
+* Don't use contractions.
-* Stick to one file per chapter unless the content is too long,
++
-  excluding reusable topics.
+*Incorrect:* Don't use contractions. +
-* Use gerunds not imperatives for chapter and topic titles -
+*Correct:* Do not use contractions.
-  "configuring", not "configure".
++
-* Terminate bulleted and numbered lists with periods unless the items
+* Use `++_italics_++` for emphasis, not `++*bold*++`.
-  listed are simple names.
+* Spell out integers that are less than 10, such as "four", not "4".
-* 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
+** Instead, 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, 
+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".
+** Instead of e.g. use "for example" or "such as".
-* Niggles
+* Do not use "&" in place of "and".
-** Do not use "&" in place of "and".
+* Do not use "and/or".  Pick one.
-** 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:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference]
 * 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]
+* link:https://mojo.redhat.com/docs/DOC-1136272[Red Hat Style Guide and Writers Checklist]