documentation

Every few months, it seems a new post decrying the use of markdown for documentation (or other things) rises to the top of Hacker News.

There are often good reasons for preferring a more structured option, like reStructuredText, LaTeX, or Asciidoc. Especially in projects where more formal text is required, or where you need to support specialized and structured text formatting.

But for 98% of software projects (and in my experience, 95% of all other text I've ever written), markdown suffices, and it is truly a low barrier compared to the alternatives. It's basically plain text (which anyone can learn to write in a few seconds) with extra features.

I've written two books entirely in markdown—specifically, LeanPub-flavored markdown—and besides plain text, it is the easiest language for general content authoring.

As you get deeper into your journey using Ansible, you might start filing issues on GitHub, chatting in #ansible on Freenode IRC, or otherwise interacting more with the Ansible community. Because the Ansible community has grown tremendously over the years—and as Ansible has been subsumed by Red Hat, which has various support plans for Ansible—there's been a greater distinction between parts of Ansible that are 'core' (e.g. maintained by the Ansible Engineering Team) and those that are not.

When everything works, and when you're living in a world where security and compliance requirements are fairly free, you would never even care about the support for Ansible components (modules, plugins, filters, Galaxy content). But if something goes wrong, or if there are security or compliance concerns, it is important to be able to figure out what's core, what's 'certified' by Red Hat, and what's not.

I've been slowly reading through "Coders at Work," an excellent book in which Peter Siebel interviews many different programmers on their work and craft, and I hit a great little snippet of advice from Peter Norvig:

"The overall design of what's going to do what, that's really important to lay out first. It's got to be something that everybody understands and it's also got to be the right choice."

Basically, before you start doing some huge project, have a bit of a meta discussion about what you're trying to do. Document the process / steps, make sure it makes sense, and code to that process. You don't need to necessarily comment on every little tidbit of code you write—code should be somewhat self-explanatory if written well—but you should at least document what your functions do, and what kind of idea you're trying to implement.

Plus, if you document beforehand, you'll be able to conform code to documentation, and at the end you'll have a framework of your docs already complete!