Why don’t we have more documentation? (part 2)

In part 1, I talked about the variety of audiences who use documentation. This variety of different audiences/roles makes it pretty hard to produce documentation that will meet everyone’s needs.

However, it really all comes down to ROI.  If your documentation will have a high (enough) ROI, management will make it a priority. So, lets start with [who is going to get the most ROI from docs and when].

ROI from the developers
The #1 team that will show ROI from documentation, is the dev team.  For a dev team, the documentation is used for the same reasons that construction-people assemble scaffolding or concrete-pouring molds, or architects will design detailed drawings and models of stuff.  It is because the devil is in the details.  Some types of documentation are specifically an exercise to make sure the developers have thought-things-out, completely.  When things get hectic, you will need to refer to the plan and it will keep you on track.  It is measurable and it keeps you from going astray. Your project stays within the boundaries that have already been clearly defined.

Time for Pain

The real pain for the BA/Dev team will surface when the docs are “tested” and “debugged” (aka: reviewed) because this usually happens at the hands of people who don’t understand what the docs are supposed to do.  Ultimately, some day, the docs will end up going to the developers.  So, the docs must be designed in a manner that will be useful for the developers. I think we can all agree that sometimes, developers talk and think in a manner that seems strange to others.  So, if the docs are written for the developers, they might seem a little strange to a non-developer.

This is when the pain really surfaces. As the docs are being reviewed by non-developers, *big surprise*, the non-developers might not see the point in all of this.  “This documentation doesn’t seem to meet MY needs”. At that point, the non-developer(s) will want to go one of three directions:

a)  This documentation needs to be changed to meet my needs
b)  Since I don’t see the value in all of this, I won’t fully-apply myself, because I don’t see how it will benefit me.
– or –
c)  I will go along with it, whether it makes sense or not, because I’m sure it provides a value to someone else in this org. Otherwise, I wouldn’t have been asked to review these docs.

It is a little hard not to laugh when you read “c”, because it is un-natural for someone to react in this manner.

The deterrent

Try putting yourself in the users’ (non-developer) shoes and see things from their perspectives: let’s say you are a sales-rep, employed by a company and you have been asked to read and approve some documentation. If you do a really great job at it, what will be your reward? Congrats, you will be given more of this work. So, instead of building your career as a sales-rep, you will end up spending more time working against your career goals as you get sucked into an IT position.

Now, if this seems like a really good thing for your career, then you will have lots of incentive to do a great job and really review the heck out of those docs. However, if you enjoy being a sales rep and are not turned-on by IT work, then you have a strong incentive to NOT do a good job of reviewing those docs because there is nothing in-it for you. Someone else, in IT will benefit, at your expense. So it is really unnatural to expect anybody to do a very good job at reviewing docs.

This same philosophy will apply to any team that needs to make documentation for another team:

  • I don’t need the same information as the people on that other team.  I am more likely to give them information that is useful to me (not them).  Since they will need different information, they will need to ask the right questions.
  • This doesn’t directly benefit me, so I want to get this over as quickly as possible.
  • I hope this doesn’t happen very often.

Also, the team requesting this documentation might be a little miffed by the lack of cooperation.  They will tire of pursuading the other team (repeatedly) to play-along and to really apply themselves:

  • Why don’t they just do this without all of the prodding and pursuading?
  • Why don’t they understand the questions that I am asking?  We are just speaking in ordinary english after all.
  • This is really testing my patience.  I am beginning to doubt whether this is actually worth it.

I have been on either side of this conflict, so I can relate to both points of view.  It can be very exhausting and somewhat demoralizing.  If you don’t have good resources and a strong resolve, it might be difficult to achieve your objectives.

So, you can see why we don’t have more documentation.  I’m sure there are some ways to improve communications and encourage others to take it more seriously, but I’m not the boss of all of those people. 

Yes, this is one spot where it hurts.


About Tim Golisch

I'm a geek. I do geeky things.
This entry was posted in IT Psychology, Methodology. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s