Monday, June 14, 2010

No, We Shouldn't Document That

"We should document that" is not an uncommon phrase. It usually means "something is a little weird and our users might take it the wrong way, or maybe they already have taken it wrong." It's a place where you're doing something your users will find confusing or non-intuitive. Consider these examples:
  • Our login page asks for "username" but we expect you to provide an email as your username. People keep clicking "Forgot username", so we should document that your username is the email you signed up with.
  • When patching the high-availability system, support must patch the passive half of the pair first. Patching the active half first leads to system downtime. We should document that for support.
  • We can register our system in DNS at installation time (go us!) but only if you provide the username and password of someone with permission to do so.

Every "we should document that" is a bug until proven otherwise.

If you have to document it, most of the time that means you've designed it or implemented it in a confusing way. So yes, please document it. Then log it as a bug and make it less confusing. Sometimes that's as simple as changing a label - "email" instead of "username". Sometimes it's harder, like making a high-availability configuration patchable from either half with transparent failover. Sometimes, it's even dependent on a third-party system, and involves moving the documentation into the product (e.g., "please enter the username and password for a user with permission to create DNS entries") rather than removing documentation entirely.

So no, we shouldn't document that. Instead, we should fix that. Let's quit with the post facto workarounds and start actually fixing the weirdness in our application up front.
Posted by at 6:15 AM

8 comments:

  1. I agree with 'Every "we should document that" is a bug until proven otherwise'.

    But sometimes the business needs, priority, available resources, where you are in the release cycle, etc requires that a "we should document that" bug be fixed via documentation, rather than a code fix.
    ReplyDelete
  2. Joe, you're right. Just because it's a bug doesn't mean it'll get fixed for this release, for the next release, or ever. Treating it as a bug allows you to make that decision explicitly, though, rather than sweeping it under the rug with a casual "it's documented!"
    ReplyDelete
  3. I also agree with 'Every "we should document that" is a bug until proven otherwise' but to a point. There are cases where if the customer submits a defect onto your product, your company has to pay for that defect, unless that has already been documented prior to release. Would documenting everything you see help prevent these costs? Or would it make matters worse by scaring customers away?
    ReplyDelete
  4. Sakamoto - sure. We usually call those "Release Notes" and specifically the known issues section. Bugs get documented in various ways; it's just important that the documentation not be a replacement for the bug.
    ReplyDelete
  5. I would say that any perceived need for documentation is a good point to think about how to simplify that documentation (possibly to nothing). As you said, if you make things work nicer/better/more obviously (or just work), you might have to write and maintain less documentation.

    If it's hard to describe how it works, perhaps it shouldn't work that way!
    ReplyDelete
  6. I think this depends on whether you are targeting expert users or not. We typically end up with a substantial bit of user documentation in our work, but our users tend to be in the application eight hours per day. Sometimes things are harder to learn, but increase the system throughput, so they make sense to keep, like the keyboard shortcuts in GMail or Excel.

    Configuration options for changing the number of request threads your web browser opens need to be documented, how to go a back a page shouldn't need to be. User documentation isn't all evil, right?
    ReplyDelete
  7. I don't think anyone is saying that all documentation is evil -- it's just a "smell" and hence and opportunity of seeing if we can make it clearer/more obvious and hence simplify the documentation.
    ReplyDelete
  8. Hi Catherine,

    Good post. I wrote one myself based on yours here http://www.testalways.com/?p=72.
    The "Release Notes" also are a too easy get-away and will not make customer very happy. But in principle I think companies usually care about usability and try to improve. But also heap of documentation is building up in parallel :)

    Sebi
    ReplyDelete

Subscribe to: Post Comments (Atom)