top of page

The Documentation Paradox: Why we love and hate documentation

Why is it that so many professionals who should write documentation, just don’t? Even if it is an essential part of their job, and they know that it is. It is the documentation paradox. Documentation is brilliant. We all love to find solutions to the trickiest problems (and then pretend we found out through our own research and not in the documentation). But we hate to have to fill in the gaps in the documentation shelves ourselves, let alone start with a full-blown documentation set.

The documentation paradox

So, what causes the documentation paradox? Here are the main causes, which really ar e no more than misguided opinions or perceptions. And not one of them is ‘lack of time’.

😔"Documentation is boring"

Documentation is part of the product or service, but it isn't the sexy, shiny bit. It's too long, too wordy. It's not very clear who it is for. It's a PDF download.

➡️Make it useful, beautiful, and use the latest tech!

There is no reason why documentation should be boring. Obviously, begin by making it useful, in that your content serves a clear purpose and is user-friendly. Also, use the right visuals, tone of voice, and the latest technology to deliver it to the reader. What's more, as the documentation that accompanies our products and services starts talking to us through natural language and AI, it is becoming sexier than it has ever been.

😔"Documentation is not essential (now)"

Feedback and praise for creating good documentation is often delayed or even invisible to the writer, who may have written it months or even years before. People tend to focus more on urgent tasks that give a quick sense of accomplishment or satisfaction. As a result, there is a tendency to procrastinate on writing, which leads to stress, poor quality, missed deadlines, and reduced credibility.

➡️Focus on the benefits today and in the future!

Change your mindset! You are communicating your ideas, solving problems, sharing knowledge. You are giving structure to your thoughts. And you’re learning along the way. You’re also helping others overcome problems, work more efficiently, if not now, then in the not-so-distant future. You are making the world a happier place! (Or, at the very least, there will be less teeth grinding from colleagues within earshot.)

Documentation is like a box of chocolates: You really need that box.

Writing documentation is essential for the success of a project, at the start, but even more in the long run. It may not be the chocolates, but it's the box. It tells you what's inside and keeps it all together.

😔"It's way too much"

Writing is a complex and challenging skill that requires a high level of attention, accuracy, and clarity. Some may have unrealistic expectations about all of those, which makes them fear criticism, rejection, or failure. They then overcompensate their insecurity through excessive revising, editing, rewriting, approval processes... A vicious circle that makes the gap between expectations and results bigger and bigger causes more confusion, frustration, and maybe bore-out.


➡️Eat that elephant, one bite at a time!

Writing involves a lot of planning, organizing, researching, synthesizing, and communicating. Break your documentation development and management down into smaller, well-organized tasks that you know you can integrate in your daily work routine. How do you eat an elephant? Well, one bite at a time. Use practical tactics to help you to get started and keep going.

Here's an example: share a community wiki with colleagues who work on similar projects. Agree not to overengineer the wiki; stick to simple pages. Make sure that you can easily copy-paste text and attach files. Don’t worry about structures and folders, use tags.

If the above doesn't work, contact us

You can overcome the documentation paradox! The more you write, the better you will get and the more you will enjoy it. And mastery is one of the key motivators (Daniel Pink, Drive: The Surprising Truth About What Motivates Us.) Seek feedback from your peers, your customers, your manager. Learn the best practices and techniques.

Documentation experts are rare, but friendly.

But seek help if there’s really too much to do or if you lack the knowledge. There are people who know how. They are called documentation consultants, technical writers and information architects.


Pink, D. (2009). Drive: The Surprising Truth About What Motivates Us. Riverhead Books.

Dainius Jakucionis, MD (2024) Procrastination: The Reasons Behind and Possible Solutions

Winters, P. (2020, March 27). Documenting With Decision Records. Medium.


Commenting has been turned off.
bottom of page