I have struggled with this for some time. Some of our projects spend more on documentation than code.
One team required "Operation Manuals". (I put this in air quotes because no one really knows what they are.) Every document is different. I asked around and found out that the operations/support team were the audience for these documents. So I set up a meeting with them and asked, what do you really need and what do you use.
What we found is they are really training materials. A new support person reads them to learn the product. Ok. If your staff changes a lot, then maybe there is value in this information.
Then, I asked what technical information do you need?
We need ERDs. Why? You have access to the database.
Not really an ERD, we need a data dictionary because you table names and columns do not make sense. We have to research issues and create reports for our customers. Ok. This has some value because lots of times we do not know our data either.
We need to know what the code is doing. Why? Do you know what the code is doing in Microsoft Word? Also, I can give you read access to the code repository.
We need to know what changed. Ok. We can do release notes.
We need architecture diagrams. What does that mean? I got three different answers. System architecture, class diagrams and application layers.
Long story short, the result of the meeting was go figure out what you need and let us know, then we will produce it but then, we need to decide who maintains it.
Weeks later, they have not responded. If they really need it, why can't they say what they need?
As leaders, we have to challenge what people say they need and understand why the need it. If you understand their needs, you might be able to give them it in a cheaper fashion or provide what they need better. Remember all this stuff cost money. Is it better for the customer to pay for features or documentation that is out of date next week and never really used?
One team required "Operation Manuals". (I put this in air quotes because no one really knows what they are.) Every document is different. I asked around and found out that the operations/support team were the audience for these documents. So I set up a meeting with them and asked, what do you really need and what do you use.
What we found is they are really training materials. A new support person reads them to learn the product. Ok. If your staff changes a lot, then maybe there is value in this information.
Then, I asked what technical information do you need?
We need ERDs. Why? You have access to the database.
Not really an ERD, we need a data dictionary because you table names and columns do not make sense. We have to research issues and create reports for our customers. Ok. This has some value because lots of times we do not know our data either.
We need to know what the code is doing. Why? Do you know what the code is doing in Microsoft Word? Also, I can give you read access to the code repository.
We need to know what changed. Ok. We can do release notes.
We need architecture diagrams. What does that mean? I got three different answers. System architecture, class diagrams and application layers.
Long story short, the result of the meeting was go figure out what you need and let us know, then we will produce it but then, we need to decide who maintains it.
Weeks later, they have not responded. If they really need it, why can't they say what they need?
As leaders, we have to challenge what people say they need and understand why the need it. If you understand their needs, you might be able to give them it in a cheaper fashion or provide what they need better. Remember all this stuff cost money. Is it better for the customer to pay for features or documentation that is out of date next week and never really used?
Comments