3

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.

Improve this question
4
  • Are you looking for a automatic solution, some software tool which solves your problem? Or some kind advice how to change your teams's behaviour?
    – Doc Brown
    Commented Sep 6, 2013 at 13:16
  • @Doc Brown: No, to me an automated solution would not be light enough - though that's just my opinion.
    – blunders
    Commented Sep 6, 2013 at 13:23
  • 1
    The "right" way to handle the "hit by a bus" risk is with code review. Documentation ain't worth diddly if you can't understand it, and you won't know if anyone can understand it until they review it, and if you've got someone who can review the documentation, they might as well spend their time reviewing the code. And if your management is worried that the entire team might get "hit by a bus", well then documentation is probably the least of their worries.
    – Aaronaught
    Commented Sep 6, 2013 at 18:35
  • I think there's a maximum and minimum here... A useful maximum, for in-code comments would be "every file header" "every method header" has useful, complete, specific comment descriptions. At a minimum? Some say proper naming does 90% of documentation's work. Of course, devs should be able to instantly work in others code they've never seen when this is true. Perhaps a minimum would be have devs fix each others code and pay attention when you hear "I can't read Skippy's modules very well." Often dealing with Skippy will involve convincing him to use simple/standard constructs not comments
    – ebyrob
    Commented Jun 25, 2014 at 16:03

2 Answers 2

Reset to default
3

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.

Improve this answer
3
  • 1
    3-6 months? My experience is if you have that much time you should be able to ramp up with NO documentation whatsoever. 2 weeks to basic reliable bug-fix submissions from, especially, senior level devs would seem the maximum. If you want to sprain your arm patting your back about docs, it should be 2 days.
    – ebyrob
    Commented Jun 25, 2014 at 15:53
  • @ebyrob: I work on a codebase of a few hundred million LOC written over ~20 years with contributions from 10s of thousands of developers. It can take a week or more to read the books just to learn how to effectively use the software. Hence "depending on the complexity of the software."
    – Steven Evers
    Commented Jun 25, 2014 at 18:21
  • Point taken, when your code-base is over 10x larger than the Windows 2000 code-base, I suppose you can get excited about a 2 week on-boarding process. Of course, 3 months is still the time at which you'd expect to assess accomplishments and make a keep/don't keep decision, not a time at which you'd expect someone to just be coming up to speed with nothing to show for it. It's not like it's expected to have memorized the entire OS code-base to work in the Office group at Microsoft (I'm not even sure it'd help most of the time).
    – ebyrob
    Commented Jun 25, 2014 at 18:39
1

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!

Improve this answer

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.