Friday, January 16, 2009

Fun Docs

Okay, so I'm on a documentation kick. I'll stop eventually.

Writing documentation is only the first part of preserving how/what/why/when/etc. The second part is using and reading the documentation. Making sure it's available to everyone  matters, indexing it well so people know what's there helps, and pointing people to this great resource you've created is essential. But once the document is in front of the person, you still have a hurdle to overcome: are they reading? Or are they snoring?

After all, which document would you rather read?

The Official Version
Ensure the following fields are completed when logging a defect:
  • Summary: This field should contain a one-sentence identification of the perceived issue. Use the active voice and describe the actual problem instead of the perceived solution.
  • Component: Select the affected areas of the product. Consider the root cause analysis that has been done as well as the initial presentation of the issue.
  • Assignee: Select the person currently responsible for triage for the primary affected component.
  • Description: Identify the perceived problem, the expected behavior, and the individual steps required to reproduce the issue. If this includes a requirement that the behavior be produced on certain environments, be sure to describe the relevant portions of the environment and note the areas that are irrelevant.

The "We're All Friends Here" Version
When you log a bug, there are some required fields:
  • Summary: One sentence to capture the essence of what's wrong. This is likely to become the bug's nickname, so make it good.
  • Component: The team that gets the issue, at least at first. Setting more than one component is okay, just explain why in the description.
  • Assignee: The lucky winner of the "you got a new bug" prize. This is the person on triage for the team you think will have to fix something. You can only pick one.
  • Description: Explain the problem, what behavior you expect, and how to reproduce the issue, paying particular attention to times and machines (which will point to appropriate parts of the logs). Well-written descriptions will be rewarded with more prompt attention.

Neither of them is the most interesting document ever. But the second one is more fun to read, and that will get you a lot more readers and a lot more comprehension. Completeness matters, but pomposity doesn't. Don't be afraid to be a bit more casual, and a lot more direct. Make your document the embodiment of a conversation rather than The Definitive Documentation(tm). We are, after all, engineers here, not lawyers. So have fun with it!


  1. How're you storing them? Is it ye olde massive directory structure, or is it a little snazzier?

  2. Most of the docs we write or that dev writes are stored on a wiki. (And a common cry around here is: "it's on the wiki!")