Training and documentation

At Drupalcon 2009 I participated in a panel discussion  about training. My contribution was to talk about documentation. This is summary of my notes. In the traditional Zen monastery, there were two notable techniques that the master would use to introduce the novice to enlightenment. The first was to have the novice sit for many hours facing a wall and concentrate on nothing but the breath. At the point where the novice was absorbed in this state of absolute peace and bliss, the master would creep up behind him and whack him on the head with a large bamboo pole. The other approach, and the one I’m going to use here today, is to suggest some koans, imponderable riddles which are intended to so frustrate and befuddle the mind that the novice would break free from the bonds of their “monkey mind” and achieve satori. At first I considered just leaving you with nothing more than koans. I thought maybe it would be cool to think that someday, years from now, you’d be walking down the street, minding your own business, maybe eating an apple, and then suddenly the meaning of the koan would hit you like a quick bamboo stick to the back of the head. Instead, I’m going to ruin it for you and explain what it means. If you’re documenting the software, you’re doing it wrong It’s common sense, right? Documentation is about the software, right? Ya tell the user how the cool software works, right? That’s a given, right? Well, actually NO! Good documentation is not about the software, it’s about the user. Good documentation is about guiding the user towards what the user (i.e. not necessarily you) understands to be success. And the only way  you’re going to help the user be successful, is by understanding a) who is the user and b) how does that user define success. It’s not possible to know everything about the user but you should at least be clear about their roles, responsibilities, priorities and their environment. Documentation is about the user, not the software. Put the cart before the horse The old school development workflow went very roughly like this:

  1. Requirements
  2. Specs
  3. Code
  4. Tests/QA
  5. Documentation
  6. Release

It’s becoming increasingly common to flip the “write tests” and “code” steps since it makes coding more predictable. Aside from helping the developer know whether a specific functionality is actually doing what it’s supposed to do, testing before coding tremendously clarifies where the development effort is going and what precisely has to be done. Designing tests for something that hasn’t been created is putting the cart before the horse, but it works. In the same way, creating the documentation for something that hasn’t been created is also somewhat counter-intuitive but it works very well. Here’s what the new development workflow looks like:

  1. Requirements
  2. Specs/Documentation
  3. Write tests
  4. Code
  5. QA
  6. Release

You’ll notice that I put the documentation step on the same level as the specs. This is because the user documentation, when it’s written before coding, actually becomes part of the specifications. Pushing the documentation up near the beginning of the development process, has the following effects:

  • It gives the developer an exact description of the desired user experience. This allows the developer to focus on figuring out how to make the underlying process happen, rather than wasting time thinking about labels and other visual element.
  • It gives the QA team a huge head start on verifying the UI.
  • The process of writing documentation exposes problems in the user experience which would be better to discover before code is written rather than after UI freeze.

Despite these benefits, it can be a tough sell. Partly from inertia, partly because it’s not the way it’s been done in the past, and perhaps mostly because there’s generally a rush to get stuff created. One of the attendees at the seminar, an instructional designer, says she gets around these barriers by deliberately not calling it “documentation”. It’s just writing up the “user requirements”. Which, in a sense, is true.



Interesting. I thought you were going to write about how if you need to document software then you are doing the software wrong because well written software should need no documentation. Which is only true in theory, reality is otherwise.

What you are describing also goes by the name of "documentation driven development". I think I agree in theory, but in reality it's very difficult to know what parts need documentation before a usable product has been built. And over-documenting can reduce the maintainability of the documentation.