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 solution.

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 process:

• 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 programmers, 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, not noise.

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 as a community can learn from each other's experiences.

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. But, why 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.

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 individual 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.

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 writing?

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 successful docs.

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 your writing.

• 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 coming 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 you've been a reader of technical documentation you'll know that these "extras" are sometimes the most utilized 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.

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