Docs Finds Bugs

Writing the documentation for an application is a bug-hunting activity. Why? Because the act of describing how to use an application inevitably uncovers errors inconsistencies between desired and actual behaviors.

In other words, an endless series of ...

WTF?

... moments, as in "WTF did it just do?"

That's why so much time is spent writing the docs for Foxhound:

• first, the Help that is built into the program as well as being available on the web, and
  

• then the Frequently Asked Questions which are only available on the web.
  

That's why, when a new release of Foxhound is feature-frozen (as Foxhound 1.2 is now), and the programming staff has declared their work 100% complete (because, presumably, they have finished unit testing, which is another way of saying everything compiles cleanly), the next step is not "Acceptance Testing".

Rather, the next step is ...

Update The Help

... which is inevitably followed by "Fix Bugs".

Then comes "Update The FAQ".

Followed by (you guessed it) "Fix Bugs" again.

Only after all the docs are up to date, and all known discrepancies between the docs and Foxhound's actual behavior have been eliminated, does the endless, boring task of acceptance testing begin.

Who should write the docs?

The developers, of course, because they know what the application actually does (the code) as opposed to what someone once asked for (the specs)... but in many shops developers are the least likely candidates for the task.

Stereotypical developers claim that writing documentation is beneath them, that it is a waste of their valuable time, when in fact they don't do it because they hate it, and they hate it because they suck at it.

And they suck at it because they don't know how to write anything longer than a shopping list or more coherent than a tweet.

So what do companies do?

Instead of teaching developers how to write (or hiring ones who can) and then requiring them to describe their own dog food, stereotypical companies turn the entire task over to professional writers who work apart from the developers.

These writers do a wonderful job of creating docs that are clear, well-written and riddled with errors descriptive of applications which simply ... do ... not ... exist.

What should companies do?

At the very least, professional developers should learn to write at a level that can be understood by the professional writers.

Then, the developers should be the ones to write the draft documentation for everything new, and to write draft updates for everything that has changed... with the emphasis on "everything".

Those tasks should be part of the developers' job descriptions, as should the acts of finding and fixing the bugs freshly-discovered differences between the desired application and the actual application.

The result is a better application and better docs.

What are unintended consequences?

The phrase "unintended consequence" usually denotes something bad, as in "slaughter might be an unintended consequence of unilateral disarmament."

In the case of "developers writing docs" one unintended consequence is a good thing: No more GUI monstrosities.

To explain how to use a GUI, developers actually have to use the GUI, and being the smart people they are, if they actually use the GUI chances are they'll see what's wrong with it and fix it.

Sadly, however, stereotypical companies don't even document their GUIs, let alone get the developers to do it. They just wave their arms and flap about...

"It's a wizard, what's to document?"

So we get GUI monstrosities, like [insert your favorite example here] and [insert another favorite here].

And that's the bad kind of unintended consequence, that's what happens when you don't get the developers to write the docs.

---