I tend to write diatribes that nobody will ever read, so I've switched to writing a quip first, with details below in inverted pyramid style so that the reader doesn't have to ask for more information.

---

I usually start with a:

# Solution:

With links to any tickets/jobs/etc. For example, the inverted pyramid puts the most important info first:

https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)

Then I'll put any relevant notes and commands that I refer to as:

# Discovery:

```

  # in a big block of literate programming (Mac only, try `curl -ks` to skip SSL checks if the clock's wrong in your shell)
  curl -s https://en.wikipedia.org/wiki/Literate_programming | textutil -convert txt -stdin -stdout

```

So that people in a hurry can skip the parts they don't need.

Edit: I edited this a lot, might need to refresh