We are trying to introduce some agile concepts to the business folks but one of our biggest hurdles is their expectations for documentation - the quantity, the authorship/ownership of the documents, the lifecycle of the documents, the timing of the authorship, and the material that should be documented. The business folks are very much in a traditional mindset. For them, documentation is a risk management tool.

What can we do to help them view documentation as a risk and a requirement? We've tried indicating in the project timelines how much extra time is spent on documentation. Their response is it helps them estimate project costs and reduces risk. We respond with empirical evidence showing it hasn't worked to date. They respond with "that's IT's fault for reasons x, y, z" and then introduce more documentation to account for IT's failings. And then it spirals on and on until the baggage is un-bearable.

Regarding authorship, we've tried to convince the business that IT doesn't want or need certain documents and that the business is capable of producing them without IT if they feel it's needed. So they will produce something, and then hold us accountable for its contents even though it is (from our perspective) un-related to us and un-vetted by us. So when we try to vet their documents, we get sucked in and then the questions of ownership and maintenance rear their ugly heads.

From everything I've read, this is a no-win situation. Is there any advice or thoughts to help us transform their expectations of documentation to light-weight, just-in-time/just good enough documents?

If needed, find more background in my previous question.

  • 1
    Are you undergoing any other process improvement techniques within your organization, such as applying Lean principles or Six Sigma? What industry is your organization in and do you need to comply with other standards such as ISO 9000 or AS 9100?
    – Thomas Owens
    Apr 4, 2012 at 13:04
  • Not sure exactly what type of documentation you are doing, but thought I'd throw this out - in many applications, particularly webapps, the need for user manuals can be mitigated by good graphic design and documentation within the app itself, like tooltips and adequate field labels.
    – Michael K
    Apr 4, 2012 at 13:35
  • We're an insurance company, but none of the documentation relates to compliance. This is purely docs to make them feel more secure with "transitioning to agile"; however, the very nature of the document requests negates many of the benefits of agile.
    – Riggy
    Apr 4, 2012 at 17:17

1 Answer 1


From what you're saying, it's probably going to be a long and arduous journey, for both you and the business.

Just remember that the business is entitled to any documents they ask for from you. If they are willing to prioritise it above other work that they want, that's up to them. I know documentation is boring, but it is part of the job.

On the plus side, you will find that there are two things you can do to ... discourage them.

First, you can make them think about the necessity for documentation. Every time they ask for a document, ask them who is going to read it and what they're going to do with it. These are valid questions anyway, you need to know how to target the docs. But it also makes them think; often these documents are things they think they should have, but they don't really know what they'll do with it.

Second, you can make the cost of documentation very visible to them. Make it a part of the task estimate, or even a separate task. When they start to lose out on functionality because of some documentation they never really needed, they'll start to rethink their documentation strategy.

Again, don't expect quick results here. The current situation is that you think they're being insanely old-school in asking for the documentation and they think you're being lazy by trying to avoid it. Teaching them that you're trying to help them out is a slow process.

  • 1
    +1 for making the cost of the documentation visible. Scrum is very good for this - when you prioritize a list of stories which includes several documentation stories, it will soon become clear just how important the various docs are.
    – Michael K
    Apr 4, 2012 at 13:33
  • I have had this 'problem" for 6 years - the process demands a certain level of docs. I can fight it every step of the way, argue how costly and ineffective they are, no one reads them etc and come out second best, or live with it, sigh, and start typing into word rather then vi.
    – mattnz
    Apr 4, 2012 at 22:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.