putting the writer back into technical writing
In the introductory piece for Web Ware, I took quite a few potshots at the
field of technical writing, damning most technical pieces as being obtuse,
jargony, and pretty much useless. I think, my summation of the situation
was, "...most technical writing out there bites the big one and there's no
sign that the situation is going to get any better in the near future."
Well I'm here to say that when you publish your opinions in the public
eye, you had better be prepared to back up your position!
Scant hours after the piece went online, I received a very valid and useful
criticism of the article which I wanted to share with all of you. Cyril
Vidergar, a documentation writer for a large computer company,
wrote me saying, "What would you want to see in
software manuals/technical writing to further disassemble the mystery?"
Well, that is a big question of course, and difficult to answer. However,
it is absolutely the right question to ask.
After all, it is one thing to complain about the shortcomings of
technical writing but quite another to actually set forward a reasonable
I am grateful that Cyril provided the slap in the face which I deserve for
only taking on the easy part in my editorial. So thanks Cyril, and here
is my best attempt at an answer. (1)
As I see it, the way to produce better documentation is a three part
I'll discuss these three aspects in just a moment. But first a small but
- recognizing that the customer is king,
- recognizing (on the part of corporate resource management) that good
documentation is as important as good code and that good
documentation demands a full time partnership between writers and
- recognizing that technical writing is a teacher/student relationship.
Like any art form (and writing, be it the writing novels or the
writing of specs for a large software application is certainly an art form)
there is no "right" way to create. So, read on. But read on with this
thought in the back of your mind: "This is what Selena Sol has learned
while writing technical pieces. Many of the observations may not be
appropriate for me!"
More importantly, if you are writing technical pieces, take time
to really work through this problem for yourself. Define your own voice and your own style. The crucial
thing is that you take time to make your writing better. After all, it is not enough to write code that works.
You must also write code that is easy to modify later; by you, or by the next programmer filling your
cubicle and code which is easy to use for the user. Take time to add knowledge to our computer culture,
You might even try writing down
your own observations about technical writing and publishing them on the web like I have done so that we
community can learn from each other's experiences.
But let's get on to the argument.
The success of software is not about bug-free code. Take Microsoft
Office '97 for example, buggy as hell, but everybody's got a copy
Neither is the success of software about the production of the most
advanced and powerful algorithms or the utilization of the
most cutting-edge user interface philosophies. How about Windows 3.1? A behemoth, but still installed
on PC's from Cambodia to Calistoga.
Bug free design and cutting edge algorithms are things software engineers
care about. But they have very little to do with the success of software.
The true success of software, is based on the relationship you build with the
customer. This relationship is built upon five factors and if you get an
"A" for all five of these factors, you have an application which
solves problems for people, making their lives easier and their work more
efficient. You may also make some money in the process.
NOTE: Documenting your code and documenting your product can be seen as one in the same. In the
case of documenting your code, you can think of your customers as all the programmers who must build
upon, maintain, and modify your code after it has been written (this could include you yourself).
Specifically, as a software producer, you must provide the customer with:
- a software package they can afford.
- the functionality they require (and nothing more).
- an easy to use, invisible interface.
- answers to their questions.
- steady improvement based on their feedback.
In this article, we will mainly focus upon the fourth factor, answering the customer's questions.
should we give a damn about customers with their
strange demands, irrational tastes, and limited knowledge?
The reason that we should care is because the ultimate goal of writing
software is not to show off your knowledge of arcane and complex
algorithms. And, truthfully, though you may not want to hear this, the
ultimate goal of software is not to create bug free code. Bugs are the
unavoidable result of software and fine tuning is an endless process
(which very often introduces new bugs).
The reason that we should care about customers is because software
is created for them, not for us. Software is created to solve
their problems; problems they define and redefine.
This is a crucial mind set which must be understood by the people who
write code and the people who write about code. The customer is king. If
an algorithm does not support the customer, it should be removed. If
documentation does not support the customer it should be rewritten.
Putting Resources Where They Belong
So how do most companies and software engineers go about writing or rewriting documentation. Well,
the sad fact is that most companies don't. My favorite quote on the
topic from my experiences in Silicon Valley is, "Well, we will deal with
documentation if we have time at the end." No joke. Someone really said this to me.
The fact is that most software companies relegate documentation to the
back of the bus.
Of course it is easy to see why. The software industry is vicious. The only way to stay alive and to make
money is to be first to market and first to innovate. That doesn't leave much time for real, quality
documentation. The goal is to crank out working, or semi-working code as fast as humanly possible in
order to beat the other twelve companies at your heels. If any stage in the process of software
development (design, development, quality assurance, documentation, marketing, sales) is going to be
shaved out of the picture, it is going to be documentation.
Further, even when companies allot time for documentation, they very often use the programmers
themselves as the primary authors. Sometimes this can be great. But most often, the programmer is the
worst person you can get to write documentation. For one, programmers are not necessarily good writers.
Like we said before, technical writing is an art form. The programmer may be a brilliant logician, but
that has no bearing on whether or not they can teach.
Further, the programmer is typically biased about and probably fed up with the code already. That is, by
the end of the development cycle, the programmer knows the code like the back of her hand and what may
not be obvious to the average Joe is certainly obvious to the programmer. Thus, the programmer will
usually not give adequate explanations of difficult ideas because to them, they are simple ones because
they are so familiar. The programmer will have no perspective.
The result of all this of course, is that documentation organizations are last on the
list of high priority employees or projects and that development is king and
documentation is...well...last minute.
This, of course, is a very serious problem. Bad documentation is not just bad for the company or the
producing it. Shoddy documentation has profound ramifications on the
development of cyberspace, and thus, is bad for everyone.
Every "newbie" that is bored, intimidated, or frustrated is one more
newbie that supports the stereotype that computers are hard to use and not our
friends. The longer that stereotype pervades, the longer it will take to
really apply the power of computers to the betterment of human society.
Granted, this is a pretty abstract idea in the middle of a piece on
technical writing, but it is one which must be in the back of the mind of
every software engineer. Progress must not occur for the sake of
progress, but for the sake of making life better. We are all responsible
for this goal in our own little, but important ways.
Documentation is more than simply a crucial way to support the
customer. Documentation is a crucial foundation upon which we will build
the information revolution. Documentation is about generating knowledge and meaning, not about data
and information. Documentation MUST have quality.
More specifically, companies must invest in documentation departments which contain both technically-
oriented staff as well as English and psychology majors, maybe even a graphics designer or two.
Documentation must be given a high priority and the ability to integrate closely with engineering during
all phases of software development from the definition of requirements to the bug testing of quality
Of course, once we have a group of writers working on documentation, we must make sure that they are
comfortable with the medium they will be working in. Technical writing, as any art form, has many
quirks which separate it from other forms of writing such as poetry, novels, short stories or news articles.
Technical writing has its own styles, tools, and tricks which make it a unique process.
So, how can we help support the customer with our documentation? How do
we answer their questions about using our products? How do we go about actually doing technical
Let's get one thing straight. Technical writing is not a speaker/audience relationship. It is a
teacher/student relationship. Technical writing is about teaching people how to use your product and your
code. This relationship comes with a few aspects which we should understand if you are to write
Understanding the Characteristics of a Student
The first thing that we need to understand before we start writing about some technical issue is that our
reader has a few general, stereotypical qualities which we would do well to incorporate into our
documentation strategy. The following list reviews some of the characteristics which will greatly direct
- Students think that what you have to say is boring
- Incorporate pictures into your text. If it looks fun, it is fun.
- Students are intimidated by what you have to say
- You may be extremely familiar with your product, class library, or code base, but that is because
you've been working with it for the last few months. Remember that your reader is probably
at this for the first time.
- Tell some jokes. Get things off on the right foot. Make the reader feel as if you appreciate the
struggle she has agreed to undertake.
- Use lots of metaphors to explain things. It is likely that the ideas and theories you want to get across
correspond to some daily activity that your reader can instantly feel empathetic with.
- Students are unfamiliar with terminology
- For goodness sakes, make sure to include more description than seems reasonable to you. The
advanced reader can skim through it and the beginning reader cannot live without it.
- Make sure you leave enough time to compile a good index, table of contents and glossary. If
been a reader of technical documentation you'll know that these "extras" are sometimes the most
resources. Nevertheless, most authors skim through them at the last minute before printing.
- Students are insightful, give them a way to send feedback
- Students learn by doing.
- Only in theory do people learn by theory. In reality they learn by example and participation. Make
sure to give them a lot of code to work through. Include the theory in between the lines. Sneak it in so
they don't realize they are learning abstract concepts.
- Students have a problem
- Your readers did not pick up the documentation to learn about the product. They picked it up
because they needed to do something with the product. Thus, make your examples useful. Make them cut
and paste problem solutions. Takes some time to predict the types of things that your customers will be
doing with your code and solve those problems as examples.
Once you have developed a positive relationship with the reader, you have fought most of the battle.
However, there are still some things which you can do in order to make the teaching process even more
smooth. Specifically, you can develop clear standards which make reading through the documentation
Let's take a look at an actual bit of documented code to see what types of standards can be applied.
- Indented comments
- README FILES
Of course, there is a huge body of literature regarding technical writing at
your disposal. I suggest that you supplement this piece by taking some time to go to your local library and
looking for some good stuff.