Hear me out before telling me how wrong I am.
Over the past couple of weeks, I have read a few different articles on writing good user documentation from a software developer’s perspective. It is an area I was always told I excelled at by people who read the docs I wrote through the years. However, by the time I stepped away from my WordPress business of over a decade, I had almost completely stopped writing user documentation. Few users seemed to have noticed or questioned why there were no step-by-step explanations of certain features.
Like many WordPress plugin and theme developers, I am a firm believer in having documentation on hand. As someone who has been fiddling with code since 2003, documentation has been my best friend. I have written at least a few hundred tutorials or pages of docs throughout my career. I have published two development books and was a technical editor on a third. I am fairly certain I have created a plugin or two with more inline documentation than actual code.
However, I also ran support for end-users for over a decade. The one thing I learned with any surety is that many users simply do not read the documentation. Even if they were reading it, they should not have needed to most of the time.
Despite iterating, redesigning, and trying my hand at everything to lead users to documentation before running to the support forum with every question, repeat questions never failed to land in the support queue every day.
It took me years — far more than it should have — to realize that the solution was not in the documentation and the problem was not in the user’s ability to read it. The problem was the product. If users were asking repeat questions, it meant there was something wrong with the user experience. Eventually, I shifted my focus. Instead of writing more docs, I focused on addressing the problems that continued to crop up in the software.
The activity that I had failed at was listening.
One of the best skills a developer can obtain is the ability to listen and then translate what users are saying into better code, user interfaces, and user experiences.
In my younger years — and I suspect many developers were the same when starting — I felt like I knew the answer to every question and was always right. I was highly skilled, and I knew it. For a young, 20-something developer, that tends to mean trouble. It means that you believe the problem is not with the things you have built. No, the problem was that the user was doing something wrong. These are the types of developers who say, “RTFM,” and point a user to an overly technical document that does not solve their problems.
Some lessons are learned the hard way, but learn them we must to build better products.
I promise if you do this one activity — listen, really listen — to users, you will spend far less time explaining how something works. The question you need to ask yourself is why a piece of documentation needs to exist in the first place. If it takes 500 words
This article was written by Justin Tadlock and originally published on WordPress Tavern.