Why you should always do documentation before development

Doc-driven development focuses your code toward a specific blueprint of how an application is meant to work.
648 readers like this.
Freer than free, opener than open: The fight for the learning management systems

Opensource.com

Programmers and project managers sometimes think the phrase "doc-driven development" means putting a lot of comments in code or working closely with doc writers as development happens. That's because it's hard to imagine how development can possibly happen after documentation, because surely documentation can't happen until there's something to actually document.

Documentation traditionally is seen as a sort of journalistic endeavor. Doc writers are given some software, and they take it into the lab and poke it and prod it until they've figured it all out, then they write it down for everyone else to never read.

This misses the all-important process that happens naturally when a developer, idly sipping coffee one evening, drums up an idea for an application. The developer may not realize it, but as the idea formulates, there's a kind of documentation happening already. Ideas don't just appear fully formed with every detail mapped out in a tidy blueprint ready to be hooked up to lonely lines of code. Ideas happen gradually.

Code is arguably an art form, so here's an analogy set in the art world.

A still-life painting represents something in the physical world. But still-life art starts with abstract shapes at first, then gets refined into something recognizable, and then gets texture added, and shading, and so on.

This process could be called self-documenting, because at each stage of the painting's lifecycle, you have a snapshot of how the painting has progressed.

Still-life drawing of an orange

Seth Kenlon, CC0

In code, these snapshots might be git commits plus really good comments. While that's great for other coders who drop in later and want to understand what part of the codebase is responsible for which task, it's not generally useful to the average end user.

In the still-life analogy, this means that while the self-documentation of a painting might be useful to an aspiring artist, it doesn't do much for the intended audience.

The end-user documentation of the painting is actually the end result: The thing the artist looked at while painting is the fully realized image that the painting is meant to capture. Should the "end user" of the painting ever want to understand the subject of the painting in its truest form, the end user refers to the actual, physical object.

Believe it or not, the same is true for code. The only difference is that the application being documented does not yet exist. But that hardly means you can't document it as if though it did.

Writing the documentation for the application you want

When you sit down to write an application, you have some idea of what you intend the application to do. I'll use the utility trashy as an example because it's narrow in scope:

Trashy is a command-line trash bin.

That's often exactly where a developer starts, but if you practice doc-driven development, it's where your main page or user manual starts, and it happens well before you sit down to code.

If your only mission statement is "write a command-line trash can," then your code is likely to go in whatever direction happens to hit you first. You may or may not know about the Free Desktop trash specification, so you might not think at first to follow its scheme. You'd probably know that there's already a trash mechanism, so your first iteration of your code would probably just dump a file into the user's established trash bin without any regard for the associated metadata that ought to accompany it.

But if you sit down and document it first, you're forced to think about minutiae. For instance, imagine this as the first draft of documentation for trashy:

    Trashy is a command-line trash bin.

    trash foo   : moves foo to system trash
    trash empty : empties system trash

Already it's more robust than the original notion because it also provides a mechanism to empty the trash bin, rather than just sending a file to it. And the only reason it's there is because the act of documenting how a user interacts with your application forces you to think of the application from the user's perspective.

It's a dry run of the difference between painting something and actually hanging that painting on a gallery wall for other people to see.

Documentation as a framework

As you continue to write documentation for your command-line trash application, you eventually come up with other "obvious" expectations that you, as a user rather than a developer, would have for such a tool. You think of conventions, like having the ability to list what files are currently in the trash bin, or even restoring a file that was moved to the trash bin by mistake (which, in turn, would probably lead you to the Free Desktop trash spec, which would educate you about the metadata you should be writing along with your files when they're moved to the trash bin).

Better still, your documentation is now your pseudo code. Your application development has gone from writing code that gets thrown out when you do your first revision to having the skeleton of your code ready to build upon:

    while [ True ]; do
    # trash --help: print a help message 
    if [ "$1" = "--help" -o "$1" = "-h" ]; then
       echo " "
       echo "trash [--empty|--list|--restore|--version] foo"
       echo " "
       exit
    # trash --list: list files in trash
    elif [ "$1" = "--list" -o "$1" = "-l" ]; then
        list
        shift 1
    # trash --version: print version 
    elif [ "$1" = "--version" -o "$1" = "-w" -o "$1" = "--which" ]; then
        version
        shift 1
    # trash --empty
    elif [ "$1" = "--empty" -o "$1" = "-e" -o "$1" = "--pitch" ]; then
        empty
    # trash --restore: restore a file to original location
    elif [ "$1" = "--restore" -o "$1" = "-r" ]; then
        RESTORE=1
        shift 1
    # trashy foo: moves foo to trash
    else
        break
    fi
    done

    # more code here...

Documentation as a roadmap

This has been a simplified example, but for a larger project the principles are even more important, and often the docs come from somebody who isn't also the developer. The result is a more focused development cycle because instead of rumbling toward a vague idea of an application, developers code toward a specific blueprint of exactly how an application is meant to work. Every menu, every button, every contextual menu has already been mapped out in the imaginary application's documentation. All the developers need to do is fill in the code.

Agile road warriors

If all of this sounds very prescribed and inflexible, don't make the assumption that driving development with documentation is not up to the agile challenge. The agile method of development needs feedback from users and stakeholders to guide the direction of what's developed next. Documentation doesn't change that. In fact, in the best doc-driven dev environment, the documentation itself is treated exactly the same as source code. It gets committed to the same repository as the rest of the sources, and it gets updated before anything else.

In fact, treating documentation as the first tier of bug reports and feature requests is a great way to shield a project against UI creep. When a user asks for a seemingly innocuous UI change in what surely is a pool of several other seemingly innocuous changes, a UI can quickly start bearing the classic mark of something designed by committee. That's because, if programmers add everything requested without vetting it through someone with a view of the big picture, in effect it has been.

Using documentation as a part of the ongoing design process makes sense. It's cheap prototyping. Five bugs requesting one new button on a main panel meant to be a clean, one-button start panel equates to six buttons cluttering a once minimal and clean slate. But they don't make it off the printed page if the start panel was documented and reviewed first.

Documentation, just like coding, isn't a one-time process done early in an application's lifecycle. Your project documentation is a living document, same as code, constantly updated and revised to reflect both the development plans and the current state of the project.

Consistency

Documentation tends to produce consistency in how an application works because the internal logic is mapped out well in advance.

It's easy to code one function as a button click during the first week of an application's development, then relegate an equally important function to an obscure right-click menu during week eight when space in the UI is at a premium.

It's harder to do that when you're writing documentation for something that has no real estate yet. It's all imaginary during the documentation phase, so you'll see the breach of logic in providing a button for one task but hiding a related task. It doesn't get left that way for long when all it costs to fix it is a quick rewrite of a paragraph, which is quite different from changing several blocks of code across many files—and potentially reworking the entire UI that you already spent weeks perfecting. When you're just documenting, you can write anything you want; it's a low-cost repair, and in the end it provides a better, smarter blueprint for developers to build toward.

Test drive a doc today

Possibly the greatest thing about doc-driven development is that there is no barrier to entry. Any non-coder can invent documentation for an application that doesn't exist, and it's surprisingly useful. The applications I've written in the film industry and education sector have all been designed by someone other than me. Sure, there's still back-and-forth user testing and refinement of something that looked good on paper but ultimately didn't work quite as smoothly as the designer had hoped, but it's far less than something without a designer. And sure, there have been times when a non-coder dreams up something way out of scope and has to be reeled in, but sometimes it's led to the developer learning some new tricks to make something actually work that was previously thought out of reach.

Whether you're a developer or just a user with some good ideas, sit down and drum up some documentation for an application that you'd like to see. Alternatively, write some docs for a version of an existing application that you think could be better. You'll be surprised at just how much it affects the way you think about software, intuitive design, and development.

Seth Kenlon
Seth Kenlon is a UNIX geek, free culture advocate, independent multimedia artist, and D&D nerd. He has worked in the film and computing industry, often at the same time.

5 Comments

When I started as a programmer in 1979, we always wrote the documentation before we wrote a line of code. The documentation was a detailed program spec, and this became the basis of the user manual. The design would probably change as the system was being coded, but the spec was changed to reflect this.

I don't cut much code these days, but when I do, I still write a spec first. Old habits (in this case good habits) die hard.

Very cool story! I think the concept of 'requirements' has somehow shifted, lately, possibly due to the prevalence of closed source, off-the-shelf software. How can you list requirements for software *first* if all you know is how to compromise? The greater industry has trained users to settle for, in this order: 1) whatever has the snazziest marketing campaign, 2) whatever can be shoehorned into their workflow, and 3) whatever more or less approximates what they actually need.

Most of us have forgotten that software is called "soft" because it's meant to be malleable enough to conform to our needs. Hopefully open source + good documentation will remedy that.

In reply to by MartyMonroe

I recall suggesting to a client that we need to do the user documentation before the spec and that before we start coding. Got a lot of raised eye brows, but I explained why: it is the architectural drawing of software that leads to the spec (blue prints) which lead to the building. Tough sell! I also explained that that doing this would change the approvial process at the end from "is this what you wanted" to "does this match the user guide that was previously approved by everyone"? In other words, we get together up front to see what we want and agree on it.

Bottom line is that it takes longer before coding starts (makes managers nervous) but decreases the coding time due to re-dos and the "hey, while your at it" affect. The project is usually done in far less time due to less re-dos and the final compliance testing is easy.

Still, the concept is a tough sell in a lot of organizations.

Dave,

Nice! Yes, I think the concept of a "specification" is almost more valuable than the concept of "documentation" for many customers. People find it pretty easy to ask "why would you want to write documentation first?" but for some reason "let's write a spec so that what you end up with is what you're seeing in your head" sounds more like good service.

In reply to by Dave Boland (not verified)

I have seen projects struggle due to the lack of a proper set of documentation on what the user interaction would be. I lead an Eclipse plugin project that started life as a collection of related technologies that were collected to make an editor and build chain for developing mobile web apps. (think pre-IPhone devices with a browser). We eventually got ourselves a UX designer, did some lab experiments with some test subjects and produced a template for the interaction that we used to finish our development.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.