How do you validate need for documentation?

Question

I once was on a project where a non-tech manager had the team spending half of every hour documenting what they just did so that someone with zero understanding of the tech would be able to understand the tech. Personally, I thought this was a huge waste, but there was no way to validate this was or was not waste.

Is there a light-weight means of validating need for documentation before committing to produce the documentation?

Example 1: Say the team is using an off-the-self software without customization. The test might be posting a job description on a monthly basis to access the likelihood that an expert in the software might be found at an acceptable cost level.

Example 2: Automatically pull variables, functions, etc from the code, and two weeks after the code is written, generating questions that automatically assess the developers own knowledge of their own code without access to the code. If the developer is unable to answer the questions, then they must explain the code to another developer, and that developer decides if documentation must be produced.

Example 3: Another way would be to take the likelihood that the code is used based on runtime analysis and cross reference it both with the volatility of input/output and historical likelihood of bugs/error being reported from that section of code and/or customer based requests to update the code.

Honestly, don't believe those are great examples, but are more of an attempt to give the general gist of what I'm after, and that the goal is the most generally useful bare-bones method for doing this.

Answer 1

Measure the time it takes for new team members to be productive. Contrast that with other resources that are available to ramp up. For instance, if you have (which I will collectively call ramp up material):

• Tutorials
• Documents (ie. help-style docs)
• Documentation (ie. API function headers etc.)
• Searchable, shared Wiki/OneNote style documents

Then you should be able to get any competent dev running at full productive capacity within 3-6 months (depending on the complexity of the software). If it's required that new devs submit some arbitrary number of improvements or useful additions to the documents and/or tutorials, then they're always up-to-date and improving.

Bonus: tutorials/documents can be made available for customers and become a part of the product.

Then, if new devs (continuously) aren't ramping up sufficiently in that time, then the quality of your ramp up material isn't in-line with the complexity of your product or the work environment, and needs to be increased or improved.

Answer 2

You have a few options:

1. Paired programming. Have the people who don't understand the tech pair with the people who do. Might slow your velocity down a bit, but it's more effective than writing reams of documentation.
2. Consult with the product owner, what are the criteria for acceptance that the product owner has established. Perhaps the product owner is unaware that this individual is spending project cycles on this.
3. Write good x-unit tests. Well written tests should provide ample documentation for the system being written.
4. Provide them with the Stack Exchange url ;)

Documentation that is truly necessary emerges, it is not the result of a contrived, forced effort.

Cheers!