Imagine you're trying to use some new software. You're reading through the docs while it downloads. The docs seem like a straightforward list of instructions for getting up and running...not much explanation about everything the software can do, but maybe that will be clearer when you're actually using it.
I've been practicing Markdown by reproducing a work sample that I originally created in Microsoft Word®. It went perfectly in StackEdit -- even generated a linked table of contents with the handy little [TOC] marker. When I published my StackEdit file to a GitHub README, the beautiful table of contents was replaced with a disappointing "[TOC]" in plain text. No good! The lack of a GitHub-Flavored Markdown table of contents marker seems to be a common complaint. It looks like there's at least one automated option (DocToc), but I figured that I could learn something by working up a manual table of contents in Markdown. I didn't find a step-by-step guide, so I patched together one way to do it from various Markdown cheatsheets and StackOverflow posts. Here's what I did.
The first style guide I ever used was a simple in-house guide, about 20 pages stapled together in the upper left-hand corner. I worked for a financial services training company with maybe 10 other employees, so the style guide was really a collection of the owner's preferences. This style guide instructed us to write "LITE" instead of "light" and to always use at least three exclamation points (!!!), never only one or two. Doesn't that sound glorious? No? Well, after you got used to it, it was great!(!!)
Sometimes, I run across a document that makes me wonder, "Who is supposed to use this?" I wonder because it doesn't always seem like the answer is "a human being!" Technical documents can be filled with jargon and showy words that make them hard to understand. The tone can be so authoritative or unnatural that any human reader would be turned off to the message. Sometimes, technical documents seem written to impress *someone* instead of to help others understand.