Merge pull request #29 from open-guides/small-fixups

Fixups and Markdown formatting

CONTRIBUTING.md

@@ -1,15 +1,11 @@
-## Contributing
+Contributing
+------------
 
-Contributions of all kinds, including discussion, corrections, additions, and improvements, are welcome!
-We hope you'll join and help, in small ways or large.
-We gladly credit all contributors and authors.
-Here are few notes before you jump in.
+Contributions of all kinds, including discussion, corrections, additions, and improvements, are welcome! We hope you'll join and help, in small ways or large. We gladly credit all contributors and authors. Here are few notes before you jump in.
 
-**Questions and discussion**:
-[File issues](https://github.com/open-guides/og-aws/issues) liberally. Don’t be shy about creating issues — they are the only way to discuss things here. Just tag it as a question or discussion. We or others can answer, and it may lead to improvements to the guide.
+**Questions and discussion**: [File issues](https://github.com/open-guides/og-aws/issues) liberally. Don’t be shy about creating issues — they are the only way to discuss things here. Just tag it as a question or discussion. We or others can answer, and it may lead to improvements to the guide.
 
-**Corrections and improvements**:
-[File issues](https://github.com/open-guides/og-aws/issues) describing the problem.  Use them to discuss topics, ask questions, identify issues, or suggest improvements. [Pull requests](https://github.com/open-guides/og-aws/pulls) with changes are even better. Please keep them small and focused, so we can add items individually, and review the conventions below.
+**Corrections and improvements**: [File issues](https://github.com/open-guides/og-aws/issues) describing the problem. Use them to discuss topics, ask questions, identify issues, or suggest improvements. [Pull requests](https://github.com/open-guides/og-aws/pulls) with changes are even better. Please keep them small and focused, so we can add items individually, and review the conventions below.
 
 Please review current issues and pull requests to avoid duplication. Finally, if an issue isn't appropriate, please shoot an e-mail to [@jlevy](https://github.com/jlevy).
 
@@ -17,18 +13,20 @@ Please review current issues and pull requests to avoid duplication. Finally, if
 
 When you contribute, keep in mind these conventions:
 
-* Terms that appear for the first time in **boldface** are defined there in a brief summary, with a link if possible to what is probably the best page for that concept.
-* References or citations backing some info that is already explained in the text is in [brackets] (with link for web pages, no link for books).
-* Related content that elaborates or gives more detail is included via inline links within the text.
-* Key and important statistics are **boldfaced **(illustrative numbers should not be).
-* References, including all references to books, are linked in brackets at the end of the bulleted entry.
-* Typographical conventions:
-    * Use Unicode open and close quotes “like this” and not "like this".
-    * Use oriented apostrophes (Unicode’s, not ASCII's).
-    * Use em dashes — like this (not two hyphens -- like this).
-* Section conventions: When appropriate please add sections covering these items:
-    * *Basics*: The elementary facts you should know if you don't yet know anything about the service.
-    * *Alternatives and Lock-In*: Should you be using this service or something else? Is the decision an important one that locks you in?
-    * *Tips*: Everything you should know about the service, from big stuff to details.
-    * *Cost Management*: Tips specific to that service on reducing or managing costs.
-    * *Gotchas and Limitations*: Common problems, large and small, as well as misconceptions and quirks.
+-	Terms that appear for the first time in **boldface** are defined there in a brief summary, with a link if possible to what is probably the best page for that concept.
+-	**Boldfaced headings:** When possible and appropriate, begin bulleted items with a boldfaced summary, as illustrated here. This helps the reader skim the contents.
+-	It’s also fine to boldface **key statements** that guide the eye. In some cases, *just use italics*.
+-	Related content that elaborates or gives more detail is included via standard inline hyperlinks within the text.
+-	References or citations backing some info that is already explained in the text is in [brackets] at the end of the item (with link for web pages, no link for books).
+-	Typographical conventions:
+	-	Use Unicode open and close quotes “like this” and not "like this".
+	-	Use oriented apostrophes (Unicode’s, not ASCII's).
+	-	Use em dashes — like this (not two hyphens -- like this).
+-	Section conventions: When appropriate please add sections covering these items:
+	-	*Basics*: The elementary facts you should know if you don't yet know anything about the service.
+	-	*Alternatives and Lock-In*: Should you be using this service or something else? Is the decision an important one that locks you in?
+	-	*Tips*: Everything you should know about the service, from big stuff to details.
+	-	*Cost Management*: Tips specific to that service on reducing or managing costs.
+	-	*Gotchas and Limitations*: Common problems, large and small, as well as misconceptions and quirks.
+
+Note we try to keep consistent formatting in Markdown via [markdownfmt](https://github.com/shurcooL/markdownfmt). We run **admin/reformat.sh** to do this, but you don't have to worry about it unless you really want to.

admin/reformat.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+# Put main main Markdown files into canonical syntax (in place!) with markdownfmt.
+
+set -e -u -o pipefail
+
+hash markdownfmt >/dev/null 2>&1 || {
+  echo >&2 "markdownfmt missing: Install https://github.com/shurcooL/markdownfmt and re-run"
+  exit 1
+}
+
+cd $(dirname $0)/..
+
+markdownfmt -w README.md CONTRIBUTING.md