“Documentation for the sake of documentation” is another way of saying “documentation that no one will ever read”.
Still, more organizations are stepping up to get docs written on their engineering, roll-outs, and standard operating procedures.
It’s all about dotting the i’s, j’s and umlauts (¨), as
Dwight Shrute would say.
I’ll admit it; documentation is my weakest link as a Sys Admin. It is often thrown together at the last possible moment, and sorely lacks appropriate formatting and flow. Any ITIL or COBIT devotees who stumble upon my documentation usually react as though they are undergoing 6 simultaneous Myocardial Infarctions though, in reality, they are really closer to the aristocratic woman who faints when she hears Eliza shout “C’mon! Move your bloomin’ arse!” in My Fair Lady.
That being said, my documentation is getting better the older I get. It’s kinda moved from writing instructions on the back of my lunch napkin to “Go that way really fast. If something gets in your way, move“. Hey, progress is progress.
There are some projects, however, where writing the documentation is more time intensive than actually engineering the solution being documented. This is only anecdotal, but it seems to me that the higher the doc word count the crappier the feature being documented. There has to be a happy medium.
So here is my take. IF your organization actually has people of interest who read and regularly reference the documentation, then it’s worth it make the docs readable and understandable. If the opposite is true and your organization writes docs for the sheer pleasure of uploading them to some maze-hidden Sharepoint directory, then you may want to save your time and use an alternate form of documenting.
Try adopting the Peter Blunt System to documenation. For those of you (which will likely be everyone) who never saw Caddyshack II, let me give you the skinny. Peter Blunt (portrayed by Randy Quaid) is an attorney for Jack Hartounian. Jack wants to build low income housing close to the Country Club. The Country Club lawyers come in to flex their legal muscles to prevent the project. Enter, Peter Blunt.
(Here’s a link, but be warned, there is some graphic language so it may not be work friendly – https://www.youtube.com/watch?v=4lURHNLrwtc )
Basically, get the job done. Don’t try and bury me in paperwork. Don’t make me write a free-trade deal. Expect documentaion and then get some Doc nerd who dreams in ITIL to come along and do the formatting and ask a few follow up questions. In fact, limit the number of questions your Doc guy can ask your Sys Admin or Developer. “You can ask Todd 8 questions. That’s it.” I guarantee you the questions asked will be very important vs. the cacophany of shrieks, wailings and gasps that WILL come if you don’t put a ceiling on it.
Don’t make me hire Peter Blunt to do it for you.