There’s an interesting tension in technical writing between knowing and not knowing. Tom Johnson, who blogs at www.idratherbewriting.com, tackled this question in an article on learner perspective. This is my take on the question of how much tech writers need to know about their subject matter.
Knowing everything about a software application that you’re documenting for an audience of technical people is probably a good thing. But knowing everything about an application you’re documenting for non-technical users (i.e., regular people) is often not a good thing at all.
The best documentation, in my experience, requires the writer to see the application from the user’s perspective. So if the user knows nothing about the application, the writer has to somehow write from that perspective while at the same time holding in mind the knowledge already acquired by either using the application or reading documents prepared by the developers that describe what the application does.
It’s an interesting paradox. By knowing less, you actually accomplish more, because you can keep the user’s priorities clear in your mind:
- How I start the application?
- What do I do if I can’t log in?
- What are the six most common tasks I have to do in the application?
- How do I do them?
- Who can help me when I have a problem?
By knowing less, you may be less likely to indulge in technospeak, because you haven’t absorbed it. And you’re less likely to over document the application, i.e., document every single bell and whistle, far beyond what most users need to know.
In many situations, I don’t even talk to the developers or read their documentation. I just start the application and try to figure it out myself. If the software is well designed, i.e., the interface makes sense, I should be able to teach myself how to use it.
In the process of learning the application, I try to create scenarios or situations the new user might experience. I look at words and labels on the interface and try to make sense of them. I stare at icons on toolbars to see if it’s obvious what they do. If it’s not, I’ll need to explain them.
Most users don’t care how an application works. Their focus, appropriately is on the specific tasks they need to accomplish. The software is never the focus of their job; the job is the focus of their job. It’s important to remember this, as obvious as it seems.
So knowing a lot of technical information about the application doesn’t really help me in this situation. It creates a barrier to simulating the end user’s mind.
If I’m doing my job correctly, I’ll use this “simulation” I’ve just described to structure the documentation in a way that reflects the user’s priorities, not the manager’s, not the developer’s, and not the IT department’s.
For many users, tasks are quickly sorted by frequency, and their need for the documentation reflects this:
There are things I do every day in the new application and I will master very quickly – I don’t need the user guide after a day or two.
There are things I do two or three times a month – I might need to check the user guide a few times.
There are things I only do once or twice a year – Help! Where is that damned user guide?
Stephen is a senior technical writer with more than 20 years experience writing for corporate and hi-tech clients in Vancouver and Toronto. He is the past president of the STC Canada West Coast chapter.