Would your coworkers know how to handle your job if you weren’t there?
This question was top-of-mind for me last week as I headed out-of-town for a family emergency. All too often, my answer to such a question has been “no” or “somewhat”. Many people in IT (consultants included) would have to answer that question the same way. But that’s the wrong answer.
We often prioritize documentation lower on our lists than “getting real work done”. We have plenty of excuses reasons excuses: “it’s boring”, “it’s tedious”, “I don’t have the time”, “no one asked me to do it”. My favorite: “I don’t need to document my project – my code’s self-documenting.” (Yup, I used that one when I was younger.) Whether your code (or architecture, or whatever) is self-documenting is irrelevant. The point of the documentation is to give the reader a brief overview so they can quickly get to the task at hand, whether that be a modification or troubleshooting. Why ask your coworker (or yourself!) to waste time trying to figure out a system? You’ve already done that.
So how to fit it in? The easiest thing to do is document as you go:
- When you’re planning the system, make notes. Use those as part of your documentation.
- Make notes when you run into something particularly tricky or troublesome or unusual.
- Write out recovery instructions while you’re fixing that problem you discovered in testing.
- Building a test enviroment? Perfect. Jot down the steps you take as you do it as a model for your production build, and take screenshots for added flair.
- And speaking of screenshots: grab them liberally, especially when you make changes using the GUI. A picture really is worth a thousand words.
If you make notes as you go, writing the actual documentation is much easier. You don’t have to write a novel, and you don’t have to write like Shakespeare or Hemingway. Just put together your notes into something coherent. Even just collecting your notes is a step in the right direction – the fact that you did something is better than nothing.
One more common excuse: the backlog of documentation that is not done. If you wait until you have time to document your entire environment, you’ll never start. The time required would be prohibitive. Instead, start from where you are now. Create good documentation for the next project you work on. Maybe add a system diagram when you have to troubleshoot a system or train a new coworker. Add a rollout plan after the next release. And plan an hour or two sometime to document that old, reliable system that you never have to modify. By taking small steps, you’ll eventually have a sizable set of documentation that covers many common situations.
The bottom line is that creating documentation doesn’t have to be difficult or time-consuming. Just start. You never know when you might need it.
This is my post for Week 1 of the SQL New Blogger Challenge. Check out all of this week’s posts on Twitter (#SQLNewBlogger).
