The intractable challenges of technical writing#
There are a few widely recognized intractable challenges1 in technical writing:
Completeness. It’s hard to comprehensively document all new features in a timely fashion and it’s hard to comprehensively deliver all the kinds of documentation that users may actually need to succeed.
Correctness. As the system changes, it’s hard to keep the docs always synchronized with the new reality of the system.
Discoveryness.2 Even if the needed content exists, it’s hard to guarantee that users will find it.
I have come to the conclusion that these challenges are not solvable with the practices and technologies of the 2010s. To be clear, I’m not saying that we should throw out the tools and practices from the 2010s and start from scratch. They are a solid foundation. All I’m saying is that we will never be able to solve the intractable challenges using only the tools and practices of the 2010s. To make further progress on the intractable challenges, we need to incorporate new tools and practices into our 2010s foundation.
Why did I write this post? Because I would like to hear from my fellow technical writers whether they agree that these are some of the most important unsolved problems in our field. The best way to advance the art and science of any field is to focus on the most important problems in that field. I am not putting forward any particular solutions to these problems because I don’t want to steer the conversation in any particular direction. Also, if these problems already had clear and obvious solutions, then they wouldn’t be “intractable challenges”!
1 Many people have discussed these intractable challenges over the years. The most recent ones I’m aware of are Riona McNamara and Aaron Gillies.
2 I am aware that the word discoverability exists. You can direct
your ire for discoveryness to Strunk & White (Express co-ordinate ideas
in similar form).
In other words, discoveryness is just a joke. RELAX :P