LookFar Labs7 March 2017

A Love Letter to Documentation: Tools and Best Practices

Damian Conway said, ‘Documentation is a love letter that you write to your future self,”

..but today I’m writing a love letter to documentation culture, the glue that keeps it all together.

The last three years have taken me from employee six at a startup to a mid-sized company growing out of bootstrapped beginnings through product expansion. Then overseas to a tech company ramping up for IPO. And most recently back to my home, literally and figuratively: the world of startups and New Orleans.

One of the first things I notice on a new project or team is the documentation. Initially for onboarding, and then, as things progress, for configuration, best-practices, and all manner of information.

In a culture that values the benefits of quality technical documentation, all types of tools, from simple to sexy, can be put to work improving your information flow and your life.

Software Documentation Tools: Simple to Sexy

Markdown

Learn it, love it. There is no simpler way to jot down notes in a widely-recognized format that can be thrown into an interpreter and made pretty. Markdown is the syntax for Github, Atlassian, and other common tools to make your READMEs, pull requests, and issues clear and concise. Your coworkers will thank you and your future self will too.

Want to see what your Markdown looks like in real-time? Check out blankslate.io. You can even save, share, and export to PDF.

Markdown goes hand-in-hand with good READMEs, which I’ve found invaluable in expediting setup of dev environments for any specific project.

Confluence

Confluence could go either way. I first experienced Confluence when I worked for ramping-up-for-IPO company, and it was a nightmare. It had multiple documents for the same thing, written by different people in wildly different departments over the years without deleting the stale parts. In practice, it undermined the reliability of all the information and left the user searching for a needle in a haystack. A seemingly decent tool, often not put to proper use.

At LookFar, our Confluence is properly maintained and a wonderful resource— which is why I’ve included it here. When kept up-to-date in a culture that values it, Confluence can be a fantastic tool to store living documents: best practices, on-boarding documentation, retrospective notes and action items.

API Blueprint & Friends

Approaching the sexy end of things, let’s talk about API Blueprint or APIB. If you work with APIs, you should get to know her. She’s a markdown syntax.

I first encountered APIB at employee-number-6-startup to utilize Apiary, a really neat tool in itself. Then again at ramping-up-for-IPO company with Dredd and Aglio. API Blueprint’s site says it best, “with API Blueprint, you can quickly design and prototype APIs to be created or document and test already deployed mission-critical APIs.”

APIB Tools:

apiary.io

Recently acquired by Oracle, Apiary allows you to hone your API design based on substantive feedback, all while documenting your resulting API and without having to write a single line of code. Apiary defines the API Blueprint spec, so it’s no surprise they make tools that take full advantage of it.

Dredd

“Dredd is a language-agnostic command-line tool for validating API description document against backend implementation of the API.”

Aglio

“An API Blueprint renderer that supports multiple themes and outputs static HTML that can be served by any web host.”

My API teammates at ramping-up-for-IPO company were big proponents of Documentation Driven Development. It was wonderful, especially when working with APIs and API Blueprint. Any issues or features resulting in a change in documentation meant that updates in documentation came first. Not only did this prevent documentation from falling between the cracks, it allowed us to take full advantage of tools like Dredd and Aglio for CI testing and validation. Two birds, one stone, because the culture fostered leveraging the tools.

Tools, Tools Everywhere

Spend 5 minutes on Product Hunt, and you’ll realize that if you need a tool for something, there is a good chance someone has built it. Yet no abundance of tools alone will fix your documentation woes. You have to put in effort. You have to nurture a culture that values documentation.

How much is too much or too little documentation? Engineers must use their own experience and judgement, but here are some examples:

At employee-number-6-startup we didn’t have much documentation, but things were constantly changing (being thrown out and re-written), and if you had a question, you could easily pick the brain of whoever designed it— they were sitting nearby. Time spent on extensive documentation was time lost toward releasing the next overhaul: culture and product, we weren’t near the tipping point of time invested vs long term value yet.

At ramping-up-for-IPO company we had all the tools imaginable but so much inconsistent, stale, and sporadically missing documentation that valuable information was lost in the weeds. Some teams were diligent, but on a company-wide scale, the culture fell short of the tools, resulting in countless wasted headaches, time, and money.

My mid-sized-and-transitioning team was pretty stellar about documentation culture and struck the balance between having just enough to cover all major systems, best practices, and common issues but not attempting to recreate Stack Overflow. Goldilocks would have said it was “just right”. Mid-sized-and-transitioning put emphasis and care into keeping documentation up to date with system and best-practice changes. Common information structures were implemented on the dev side from tickets to pull requests, so that anyone could jump in with basic context and add value. These practices are attainable irrespective of any documentation tools— offering a fantastic return on investment in terms of headaches, time, and money.

At LookFar, we are in the middle of creating and refining our best practices for documentation. We have separated living documents from static ones (contracts, bids, etc), housing them in two different systems, and that has worked well thus far. We have READMEs for many projects on the dev side, but we certainly have room to grow and improve those, as well as our information structure for tickets and other information hubs. Documentation has no end destination until your project/company/product is dead, so hopefully yours is never “done.”

There are many best-practice reasons to document your systems and your workflows thoroughly— but at the end of the day, crafting a culture that values quality docs will save you headaches, time, and money.

What are some of your favorite documentation tools? Do you tend toward the simple or sexy?

Written by

Elizabeth Kukla