From e95f73e8a52f090b2442ad5565f7a2482dbcc452 Mon Sep 17 00:00:00 2001 From: Matthew Helmke Date: Wed, 15 Nov 2017 09:45:26 -0600 Subject: [PATCH] cleaned up existing styleguide file and fixed a minor format issue in the contributing file --- internal_resources/contributing.adoc | 6 +++ internal_resources/styleguide.adoc | 76 ++++++++++------------------ 2 files changed, 34 insertions(+), 48 deletions(-) diff --git a/internal_resources/contributing.adoc b/internal_resources/contributing.adoc index 15840f9ceb..1727de16d2 100644 --- a/internal_resources/contributing.adoc +++ b/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` diff --git a/internal_resources/styleguide.adoc b/internal_resources/styleguide.adoc index 07763fe038..a2157adc68 100644 --- a/internal_resources/styleguide.adoc +++ b/internal_resources/styleguide.adoc @@ -3,9 +3,12 @@ == 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 @@ -13,60 +16,37 @@ ** Unsure of the proper capitalization? See link:http://titlecase.com/[http://titlecase.com/] * Write clear, short sentences. * Use definite and indefinite articles like _an_ and _the_. -* 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". ++ +*Incorrect:* Create project. Delete object from editor. + +*Correct:* Create a project. Delete an object from the editor. ++ +* Start steps with an active verb, such as *Enter*, *Edit*, and *Click*. +* Start headings with gerunds (verbs that end in -ing), such as *Configuring*, *Creating*, and *Installing*. +* Use *bold* for GUI items. Match the capitalization you see in the GUI. +* End entries in bulleted and numbered lists with periods when the entries are complete sentences. +* Use `$ sudo`, not `#` for superuser terminal commands. +* Don't use contractions. ++ +*Incorrect:* Don't use contractions. + +*Correct:* Do not use contractions. ++ +* Use `++_italics_++` for emphasis, not `++*bold*++`. +* Spell out integers that are less than 10, such as "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, +** 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, 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. +** Instead of e.g. use "for example" or "such as". +* Do not use "&" in place of "and". +* Do not use "and/or". Pick one. + -== 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] \ No newline at end of file