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 to explain a feature, there is a good chance the feature does not make for an ideal user experience.
When building products, we should always strive to build them so that there is no need for documentation. Or, at least build them so that reading the manual is a last resort for addressing problems.
For practical purposes, as a fulltime developer in the past, I kept a simple text file with a list of repeat questions. This could be a more elaborate setup for a team, such as creating GitHub issues. My text file worked fine because I was a one-person show. I would make it a habit to routinely go through the list and ask how I could improve each point. Some items were never scratched off the list. However, more often than not, I learned important lessons about building for end-users first. I could see the things that made sense in my head but were confusing to others.
The biggest improvements were not in finding solutions to existing problems but in recognizing problems within new products that I was building based on past experience.
Over time, most of my documentation became geared toward developers. These were primarily tutorials on using APIs, hooks, and other developer-related features — things that were not exposed through a plugin’s UI. I was writing far less for end-users because I was updating projects based on their feedback and questions. Yes, I absolutely failed from time to time, but I was getting better at being someone who listened to problems and made changes based on what users were telling me in their own way.
When I say that the best documentation is no documentation, I do not mean that you should skip it altogether. I want you to ask the question about why the documentation needs to exist. Are there things you can do to make the user experience easier? Are you actively tracking support questions and addressing those in the product itself?
In development, we often talk about writing “self-documenting code.” This is a way of saying to write code in a way that you should not have to explain it to another developer via inline documentation. For example, the wp_insert_post() function in WordPress tells you that its purpose is to insert a post. The goal of any software should also be to create self-documenting interfaces and other elements that a user interacts with. Users should be able to automatically understand the purpose of a button, text field, or checkbox without consulting the docs.
The next time you sit down to write a new user-oriented piece of documentation, make sure that you are not using it as a crutch to prop up a poor user experience.
