You can get stuff done faster and be more green by reducing the amount of documentation your team produces. Who would have thought that agile and environmentalism can coincide? Of course, sometimes we do need to document, because it will save us trouble, pain and money down the road. But how does an individual or team decide when to invest in documentation? Here’s a handy checklist of questions to determine whether that document really is worth creating. The answers (or lack thereof) to these questions will shape more valuable documents and keep you from generating unnecessary ones.

  1. What recognizable benefit will this document provide within the development or maintenance cycle? This is a good litmus test. If you can’t answer this one just stop now. Otherwise, take the answer and proceed to question two.
  2. Does the benefit of the document outweigh the cost of producing and maintaining it? Just because it’s helpful, we still have to ask, is it helpful enough?
  3. Who owns and who updates the document? If we cannot answer this question and get buy-in from these individuals we will likely have a document that does not provide the value we had intended.
  4. Who is the audience of the document? Documents don’t read themselves … at least not yet. Who are the consumers of this document? Perhaps a domain expert who reviews the business logic of the application to confirm that the team has completely understood the flow of some complex and critical functionality. Or perhaps the team that will support the application once it goes into production. Do I need to add that the document should always be written so it speaks to its audience?
  5. Where will the document live? As close to the as possible to the people who will write, update, and read it. If it is design documentation, source control it with the code. If it’s business or domain documentation store it where-ever there is shared (and ideally version-controlled access). If it’s user documentation please please please build a simple help system and link to it from the application.
  6. Who is the reviewer or approver of the document? This may be the same as the document’s audience, or it could be someone else. For training or help documentation, for example, you may not have access to your audience when the documentation is created.
  7. When will you stop updating the document? Now that you’ve decided that it is important enough to write the document, you need to determine when it is no longer valuable to maintain or update the document. The business logic review document I mention above, for example, may no longer be valuable once the review is complete.

One Response to “Questions to Ask Before Introducing a New Document”
  1. [...] cannot stress this enough–be written in plain English. (If necessary, consult my post on reducing documentation waste to confirm that you really need to write a solution sheet in the first place.) Slap a set of [...]

Leave a Reply

To prove that you're not a bot, enter this code
Anti-Spam Image