Automate all the things with live documents

Documenting is a pain. Unless… our code, documents, and tests are all one-and-the-same. Executable runbooks and doctests!

There’s never enough time to get everything done.

It’s loads of fun to just “code stuff up” and get it done, show off a fancy demo, and hear everyone oooh and ahhh. Or, build out a slick CI/CD pipeline that gives each developer their own ephemeral environment, tests the heck out of new code, blocks all the threats, and then shuts itself down all without incurring any noticable cost. That gets plenty of oooh’s and ahhh’s too.

But now I have a problem — it only works because I know how to keep it working. So… time to write some good documentation. Get those APIs discoverable. Document all the DevOps magic so someone else can understand what I just built.

Except that there’s always more to do — and if I write all that documentation, then I’ve got to maintain it too. Right?

Everyone hates writing documentation. But, everyone loves it when things “just work” and their job is easy-peasy. So, why not do it right and reap the benefits? We should be writing “living documents” that actually make ou…