Most documentation is useless. These types are absolutely vital.
Also in response to the article on “Documentation is a bit like people dying”, I also find that none of my clients believe in an afterlife, or at least none of them reach out to me after I pass on. ;)
I agree on technical code documentation. The best form of technical code documentation is a well written integration test. At least it feels like that, not sure if anyone else ever feels the same.
Also the best form of technical documentation are function names. This also assumes you’re not shoving tons of code into the same function. (1 metric ton = 30 lines of code.)
All code documentation that isn’t written into the code is pretty useless. I’ve also noticed the people most interested in coding are managers that no longer code. They say, I’m not going to use this but it would be nice to learn so I can support others. It’s like death bed repentance- sorry folks, you’re going to hell… er, I mean, you still won’t understand the code.
Instead of trying to come up with meaningless technical documentation about what is already written, have regular code review sessions. You know, like how you should be calling grandma on mother’s day instead of saving up for a bouquet of flowers and a catchy tag line for the funeral home guest book.
If you do feel the need to write, write samples of how to create new functionality using existing code. Document for reuse. But overall, just write simple code or else create a document that says, “please kill me now.” We all fret in retrospect about whether it would’ve been easier to fix a problem or just write it all over again.
There are forms of documentation that are very much needed.
Business documentation. Please. Please… There’s nothing worse than trying to troubleshoot a half million dollar accounting bug on several thousand lines of code, and when you ask the accountants why the software does what it does they give you a blank face. (This is also how I ended up learning the basics of accounting.)
Just as important, integration. This means your network topology and other spelling out of exactly how system A works with system B. (Don’t forget to explain what those acronyms mean.) And while I’m on a paragraph about integration, let’s call the database an integration. It is a totally independent system with its own language. If nothing else, a data dictionary can go a long way.
Last, keep documentation on how to setup your environment. I’ve proudly stampeded through the trial and error of getting an application working without having an actual current database schema provided. I documented what process I went through. I was a pioneer. Then the contractors hired to replace me took the next six weeks setting up their environment in spite of the several emails I sent all ending in “this step was just like step x in the documentation and why are my eyes bleeding?” So yeah, there’s no such thing as fool proof environment setup documentation- there’s always some new fool who’s got something to prove. (Or maybe the other contractor team got assigned a driver developer to lead a web project because his bosses needed more utilization.)
But yes- besides integration, business and environment setup- your last hours would be better spent on your bucket list rather than a boring cliff notes autobiography. The next time I get asked for documentation I’m going hand over a Bible and say, “read my words, for they give life and never die.” Then inside the Bible will be a gift card to Pluralsight and Udemy.
If you enjoyed my response, please recommend and press the heart.
Hacker Noon is how hackers start their afternoons. We’re a part of the @AMIfamily. We are now accepting submissions and happy to discuss advertising &sponsorship opportunities.
To learn more, read our about page, like/message us on Facebook, or simply, tweet/DM @HackerNoon.
If you enjoyed this story, we recommend reading our latest tech stories and trending tech stories. Until next time, don’t take the realities of the world for granted!