Documentation Design: Lets UX the Man Page

I’ve never met a developer who enjoys writing documentation. I’m not entirely sure they exist.

It’s not that we don’t think it’s important: most of us would begrudgingly agree that having well written documentation of what our system does would be incredible to have. And I think most of us have (or will, at some point) written up a Confluence document or something about some particularly tricky piece of code we’ve written. But most of the time, we’re happy enough to call our code “self-documenting”, or at most throw a few comments in the code and call it “Documented”. I mean, we built tools like the Nelmio API Doc Bundle just because of our tendency towards this.

And even if you did write that documentation, where does it go? Who’s going to read it? They’re probably just going to dig through your code anyway, because they either won’t be able to find your document, or won’t be able to understand what you were trying to say at the time. And “They” is, in all likelihood, “You”. You’ll never be more embarrassed as when you find a document, say “who wrote this POS?”, and then notice the by-line says it was you.

The reason this all happens is we tend to think of documentation as a secondary job: we write the code, we test it, and then we write some documentation on it. And then we throw it up somewhere so someone else can maybe find it with the right search query. We’re focused on making the thing work, not talking about how it works.

I think we can do better, though. We can use lessons from other industries to guide us, we can build out some frameworks in our documentation stores to make it easy, and we can start thinking about documentation before we start thinking about software. Lets jump in.

What to Put Above The Fold

Most people have very short attention spans, especially when it comes to reading. Newspapers have known about this phenomenon for decades, and as such they write articles in a particular style to get the most impact. If you look at the design of a news article, from a purely technical perspective, they follow a formula: The title gives the overall gist of the article, and each paragraph gets more and more specific on details. This is done to allow readers to figure out if they’re interested in the article as fast as possible. The information contained “above the fold” should allow the reader to figure out their interest level, and whether they want to read on.

Now think about the last time you were searching for documentation. You probably googled a few key words about the problem, clicked into whatever you could find and skimmed until you figured out if this was the right document for your needs. The longer you had to skim a document, the less likely you were to find anything: quickly looking for keywords is actually fairly brain intensive and you get tired quickly. If you could tell what the document was about in the title and first section, that would help out a lot. We know what we want when it comes to reading documentation: A quick overview, to show us if we’re interested, then details on implementation and finally, other quirks.

When writing documentation, however, that all goes out the window. We tend to focus on what’s interesting to us, the people writing the code, and that’s the quirks! The oddball edge cases that we spent hours or days working out, or the clever algorithm you used to implement some small feature. We’ll gloss over how a function is supposed to be used, because to us, that part is obvious, and we already implemented it. We tend to write documentation for ourselves in the present, rather than for others in the future.

So what should we do? Take some time to pick apart some news articles on a technical level. The subject matter isn’t particularly important, just notice how it’s written, how it draws you in, how it tells you what the subject matter is, and how it gives you details on the story. Now, compare it to a well written piece of documentation you’ve found. If you’ve never found documentation you like, I think Laravel’s documentation is particularly good. Think about how you can update your own docs to help future readers sift through your information, while still providing all the intricate details that someone may need.

Organization: Make it a Library, Not a Pile

What do you do with a document once you’ve written it? Where does it go? At my current company, we use Confluence, which is a really great tool for collaborative document building and sharing. So we’ll write up a great piece of documentation in confluence and we click save and then…what? If you’re like a lot of places I’ve seen, it goes in a section called “DOCUMENTATION”. It has a title called “v3/units documentation”, and it goes next to the 3 other documents with the same name in a long list that no one is going to look through. The next time someone works on that code, they’ll write a 5th version of this document.

I don’t mean to pick on Confluence in particular. This happens all over the place: we write documentation because someone told us we should, and then it gets lost in a sea of other docs that no one reads, because no one knows they exist. I know that several times someone has asked me if documentation exists for a function, and I’ll say “Oh just search for….” some random, hard to guess keyword.

No one should ever have to ask if documentation exists. That’s not because it always will: we know damn well that docs don’t always get written in a timely manner, and they don’t always contain every piece of information that might be necessary. The world is not perfect, sometimes people are just going to have to ask for help. But knowing whether a document exists should be easy to find out. How do we do this?

It starts with creating a documentation library. Having one list of DOCUMENTATION with hundreds of entries is not feasible to read through. We need to split things up into hierarchical sections and sub-sections. What these sections are will obviously depend on your product, so I can’t define them for you. The hierarchy shouldn’t be very deep: No one wants to click through 5 layers of decision trees to find a doc. We should also keep the sections relatively small. This is hard to judge, but there should probably be less than 10 entries in each section. Your mileage may vary, figure out what works best for your organization. Most importantly, once you figure out your hierarchy, it’s important to stick to it. You want people to trust that your documentation library is a source of truth; that if they can’t find what they need, then it’s probably not there.

Second, you need to up your title making skills. A title needs to be short enough to be read at a glance, but descriptive enough to know what is inside. Remember the news articles from before: they’re designed to tell you if you’re interested at a glance. Your document title should be too.

Third, try to include tags and common search terms in the document if you can. People aren’t just going through your hierarchy, they will also want to search. If people are asking you for documentation that already exists, ask them what they searched for! It might make sense to add those terms to the document so that it comes up next time.

Documentation Driven Development

We talk a lot about Test Driven Development in the software world. If you’ve never heard of it, there’s plenty of articles and blog posts about it, but the basics are you should write the tests for a function first, and then write code that passes the tests. It’s a great way to write code if you can do it.

I say if, because it’s impossible to do if you don’t know what you’re building. It’s very difficult to write tests without clearly defined requirements. This is sort of the point of TDD, it keeps us from flying blind and building something that’s messy and unmaintainable. But the truth is that, especially in internet based development, vague requirements are par for the course. We can try as hard as we like, but sometimes we have to just start writing.

But, there’s another option: Documentation Driven Development. The idea here is that we start by writing out the documentation. We create the confluence page (or whatever system you choose) in the best place we can find in our hierarchy, and we just start writing a document based on everything we know about the problem. Start with the title, write the first paragraph that draws us in, keep going as far as you can with what you know.

From there, we can start building tests if you want to follow TDD, or start on a proof of concept if we still don’t have enough information. The document gives you something to read to keep you on track with what you know, and something to update along the way as requirements come to light or implementation details are created. It’s a living document that you can and should update as you build.

This approach gives you a lot of benefits. First, you have a documentation page that is at least partially correct, which is more than we can say for 90% of the code on the planet. You have a document written in plain English (or your language of choice) that you can share and develop with your product owner to help gather extra requirements and shed light on issues you may be facing. Third, and most importantly, you have a document in place that can be updated. Updating a document is so much easier than creating it from scratch. You’re getting the hard part out of the way right in the beginning.

What’d We Learn?

I think that, as a community, we need to remember that we are human. Humans like for things to be simple to find and easy to understand. We like to imagine that developers bask in the glow of technical jargon, and can figure out the thought process behind our code because we wrote it nicely. And the truth is that we can do that: we dive into uncommented, undocumented code all the time; that’s part of the job. And sometimes that code you wrote really is self-documenting (probably not, though). But if we can make it easy on our coworkers, colleagues, and our future selves, that makes for a better ecosystem. That makes for happier humans. Lets aim for that.