“It exists!” he cried.
“No,” said O’Brien.
He stepped across the room. There was a memory hole in the opposite wall. O’Brien lifted the grating. Unseen, the frail slip of paper was whirling away on the current of warm air; it was vanishing in a flash of flame. O’Brien turned away from the wall.
“Ashes,” he said. “Not even identifiable ashes. Dust. It does not exist. It never existed.”
“But it did exist! It does exist! It exists in memory. I remember it. You remember it.”
“I do not remember it,” said O’Brien.
— Excerpt from 1984 by George Orwell
“If it isn’t documented, it didn’t happen.” — Sohail Sangi
Chores. Taking out the trash. Doing the dishes. Cleaning up the room. You don’t like doing them. Neither do I. Yes, I’ll admit it: I’ll do just about anything to avoid doing them.
Chores exist in the workplace, too (filling out your timesheet, checking your email, and so on).
However, documentation is not a chore. Why do I say it isn’t?
Because chores at least get done.
A show of hands: how many of you work in a place where everything is well-documented? Obviously, I can’t see everyone’s hands, but I’d be willing to bet that not a lot of them go up.
I have seen way too many cases where documentation is ignored — often blatantly so. In my tech writing presentation abstract, I go as far to say that “documentation is one of the most critical, yet most blatantly ignored and disrespected tasks when it comes to technology.” I go as far as to compare documentation and technical writing as being the “Rodney Dangerfield of technology tasks.” It gets absolutely no respect at all.
I once told someone that I had technical writing experience. His response? “I’m sorry.”
As someone who harps on documentation and communication, this baffles me. It absolutely bothers me when important things are NOT documented.
Folks, I get it. I understand that people don’t like to document. It’s not a sexy task. Some people believe that watching grass grow and paint dry is more exciting than writing documentation. People don’t like doing it.
But the fact is, it’s important!!! Here is a sampling of links I found that describe why documentation is critical.
- “Your Lack of Documentation is Costing You More Than You Think” by John Sansom
- “Lack of Documentation a Common Audit Finding“
- “Importance of documentation” by S R Balasubramanian
- “What are the worst consequences of the lack of documented specifications in a software project?“
- “How essential is Documentation in Software Testing?“
Occasionally, when I have an idea for a new presentation topic, I’ll post it to the forums on SQLServerCentral for feedback. When I posted my idea for my tech writing presentation, one of the most profound responses I received was from Jeff Moden, who wrote this response.
So why are documentation and technical writing tasks so universally hated and disrespected? I don’t have any evidence or data to answer this question (maybe if I decide to pursue a Ph.D, I might focus on this as a point of research), but I can speculate on some possible reasons.
- “It’s boring. I just don’t want to do it.” To my knowledge, nobody has ever said that documentation was fun (well, there might be a few people out there, but I digress). But there are some ways to make it more fun (more on that below).
- “I can just remember everything in my head.” This probably qualifies as being one of the biggest lies of all time. Can you tell me exactly (and I really mean exactly) what you had for breakfast yesterday, or the day before (or this morning, for that matter)? Yeah, I didn’t think so.
- “Nobody documents anymore. It’s not a big deal.” See my comment above. This is another huge lie. Especially in this day and age where misinformation spreads like wildfire, documentation is critically relevant.
- “It’s not a priority.” It absolutely must be a priority. Documentation needs to be included in project planning. Make sure that time is budgeted for documentation. It is that important, people!
- “I just don’t have the time.” See my bullet point above. Make the time, damn it!!!
- “I’m not a very good writer.” Not everybody is. Keep reading for my thoughts on this.
So what are some possible solutions to these issues? Again, I am speculating on a lot of this, but here are a few things that seem to have worked.
- Always follow the KISS principle. Keep it simple, stupid! This may be one of the oldest rules in the book. Nobody wants to write a lot of detail, and nobody wants to read it, either. Sometimes, the less you write, the better.
- Find a way to make tools easily accessible. Some of my past jobs included keeping a “scratch notes notebook” (in pre-online days) or incorporating a departmental intranet, Wiki, or team collaboration product (such as Confluence, GitHub, or SharePoint). Having the tools readily available makes it more likely that they will be used.
- Establish guidelines. It seems like people are more likely to document when rules are laid out for them. It can be something as simple as creating a template for people. I’ve noticed that when documentation guidelines are established — developing a template or a form for people to use, asking people to write comments when coding, and so on — people tend to stick to them.
- Document your code. I had professors in college who used to dock points from my project grades if they weren’t documented or commented, regardless of how good my code was. If you’re a developer or a programmer, code comments are probably the easiest and most effective ways to document. Code comments can explain, in just a few lines, what some pieces of code are doing and why some variables are being used. This allows for easier code updates, troubleshooting, and debugging.
- Don’t worry about grammar. As a self-admitted grammar snob, this statement is probably anathema to people like me. However, writing ability could be a potential roadblock to documentation. Human beings tend to be self-aware about their mistakes, which prevents them from doing their best, and documentation is no exception. If you are self-aware about how you write, go ahead and write without grammatical restrictions. So long as ideas are conveyed and understood, it should not be a roadblock. If your document needs to go to customers, have an editor (or someone who knows what they’re doing) review it and make it look pretty later.
- Find a way to make it fun. Even my own attention span is reduced and my eyes glaze over after spending a couple of hours working on documentation, especially text. However, I’ve noticed that working on some types of documentation — especially anything that involves illustrations, visualization, and UX/UI — tends to keep my attention much more than writing instructions or text. Humans are visual animals, and we are more receptive to visual cues. Creating (and consuming) illustrations tends to be easier (and more fun) that consuming text
- Be a subject matter expert (SME). Maybe the answer is that you don’t have to write at all. If you really don’t like to write, then make yourself available to someone who does, and let that person worry about the documentation heavy lifting. Sharing your expertise contributes to documentation.
This is by no means a comprehensive list (as I stated earlier, I’m speculating on a lot of this). If you have anything more to add, by all means, please do so in the comments. Your ideas might just make their way into a future presentation or ‘blog article.
I absolutely believe that ignoring documentation is a recipe for disaster — maybe not immediately, but it will happen somewhere down the line. These issues (and maybe some others I haven’t thought about) must be addressed. Documentation can pull your butt out of the fire and save it. The lack of it can guarantee that you go down in flames.