Documentation checklist

Make sure all the documentation on your project is fit for purpose and whenever possible follows a simple rule — less is more

Photo by Wesley Tingey on Unsplash

Problem statement

This first issue of our quick bites addresses a problem: “How might we better decide whether we need a new document or not?”

Mindset

When creating extra documentation on projects, apply the following mindset as described by Angela Wick[1]:

• Replace “one size fits all” with “adapt or die”:

  Every project has unique documentation needs. It’s ineffective and inefficient to apply the same approach to every project — teams need to adapt. Use existing examples and common practices as a starting point, and apply common sense.

• Let Value Be the Judge:

  Instead of passively accepting the status quo, value should be the judge of every proposed piece of documentation. Is there value in a new word document, or pdf, or confluence page? Is the value higher than the effort to create it?

• More is not better!:

  What is the thinnest/lightest version of documentation we can use to deliver value. Be lean.

Checklist

Apply this checklist to do a quick health check before introducing a new document/document type to a project.

User — is it useable?:

• Is there a defined user/consumer for this new document?

• Are they really going to use/read it?

• Do they require the level of detail I’m going to use?

• Do they have an avenue to ask questions/provide feedback on the new document?

Lifespan — is it durable?:

• Will the information be used for long enough to warrant a new document?

• Will the information remain accurate for long enough?

• Is it feasible to maintain the document after it is created?

• Can I create the document now, or is accuracy so important that the document should be created just in time later in the project?

• Will the format of the document work based on what we know about its lifespan?

Cost — is it feasible?:

• Is someone willing to pay for this information? Do we know why?

• Do we know how much it will cost to generate the documentation (an effort to create, to interact with contributors, to review, to maintain)? Is it an acceptable cost?

• Does the expected value justify the cost?

Necessity — is it needed?:

• Are you creating the document based off necessity not fear? (to cover yourself in case something goes wrong?)

• If the document is fear-based, does it still boost solution value or does it just increase time and cost?

Format — is it accessible?:

• Is it the most efficient format to deliver value?

• Are we using a particular template because it adds value? (not because of some old governance requirement)

• Will the users be able to access it in the format/location that you plan to use?

If you answered YES to all the questions, you probably need to create a new document/type of documentation. If some of the questions were answered as NO, I’d recommend you think again and proceed only if you strongly believe you need to.

Depending on your project and your team, your documentation might be extremely lightweight like post-its and scribbles on the wall or it may become a full-fledged documentation repository. Both can work and are good solutions, as long as your documentation decisions bring value and are made consciously.

Use the checklist above to help make your mind if you really need that extra piece of documentation ;)

References:

1. https://www.batimes.com/articles/get-off-the-documentation-hamster-wheel/