README.md

Markdown is pretty simple. A few `#`’s, `*`’s, and `-`’s and you’ve got a formatted document. Unless you don’t.

But you know where markdown files really shine? As the lowly README.md. Not to be confused with Reamde, which is excellent, but something completely different.

That README file is amazing for a whole slew of reasons. Not the least of which is that, since by convention almost all files have lower case names, it’s right there at the front of your directory listing, right next to your Build(.bazel) file and/or your Makefile and all of the code it’s describing. So it’s very easy to find.

README.md is easy to edit. It can be as simple as an ASCII text file, so your favorite IDE, even if it’s nano, will do just fine. All of the typography marks are just ASCII characters in the right places so it’s easy to type.

It’s also easy to read, and the typography marks do a really good job of letting you know not just that the author was marking something as special, but also how. Heading marks indent further for things of lower importance. Unordered lists look like lists, quotes look like old-school email forward/quotes, and bold/italic sections stand out clearly, even if you’re not sure which one is which.

So they’re easy to find and easy to write and read. Dayenu. But there’s even more.

The other part that’s important is that it’s a single file. Which means that in practice it’s not too long. If it gets too long you’ve probably got the wrong metaphor or are documenting at the wrong level. If you need to show more detail you can create another README.md deeper in the tree and reference it at the higher level.

And if you want a bigger set of online docs there’s doxygen/mkdocs to build a nice searchable website out of the various README.md files.