How much does a writer need to know?

By | June 6, 2016

You might think this is an odd question for a writer to be asking, but it isn’t, really.

We might assume that the more a writer knows about the subject matter, the better. And by “more”, I mean more facts, more information, more context and ideally, more wisdom and understanding.

Generally this is true for most forms of writing, such as non-fiction and journalism. In fiction, we assume the story is made up, but if the setting is modern-day New York City the physical details of that setting should be correct.

In technical writing, the kind of writing I do to earn a living, there’s an interesting tension between knowing and not knowing.

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?

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.