Fog Creek Software
Discussion Board

An answer from a former Tech Writer

Joel asked the question, "Why does every technical manual and book include a section at the beginning on 'conventions used in this document,' full of ridiculous and useless tips like, 'Tips are indicated by a lightbulb icon in the margin'? Is it because you're paid by the word?"

I was working as a full-time Tech Writer and wasn't paid by the word and I have written a "conventions" section in my online help as well as printed manuals. The reason that I can remember for this is users are way dumber than developers. The other reason is mostly mob mentality, "everyone else does it, so it must be a convention to make a Conventions page." You don't ask many questions when you are a Co-op (i.e. paid intern) student, you just accept this as part of the style of Tech Writing. Then you pass it on to the next people who come aboard. No one really praises or complains about it - except QA who will file a bug if it isn't there - so it will tend to always show up in any kind of technical documentation.

Thursday, April 17, 2003

I've worked with several technical writers and I also agree that "basics" introductions in well written documentation take a bum rap. All that this material really does is establish a baseline for the material that follows in the documentation, but it's not filler if done correctly.

The thing is, most technical implementors rarely succeed in teaching most technical concepts to end users, so the judgement of a techie on "superfluous" documentation is often (even usually) wrong.  The reason is, we are used to dealing with our own kind who are generally resourceful in following technical discussions and in following uneven transitions in subject matter and incomplete explanations.

I've found that most end users and indeed, many programmers do not even know how to *learn* and have to be spoon fed. That's the difference between a real engineer as a professional, and an end user. A engineer is often able to take disconnected pieces and see patterns emerge. By definition, an end user has to have the path laid out. And the material has to be paced and introduced in a task oriented manner rather than "simply" explaining "how it works", which totally loses the unwashed proletariat.

Bored Bystander
Thursday, April 17, 2003

I would imagine that technical manuals and books start with a "conventions used in this document" section for the same reason that airline flights start with a description of safety procedures.

Thursday, April 17, 2003

To fill in time whilst taxi-ing? So you know what to do in a crash? To give the cabin crew something to do?

John Topley
Thursday, April 17, 2003

For the 1% who have never flown before.

Thursday, April 17, 2003

I wish this type of thing was practiced more often in real life.

Often I've been in meetings where, after 15 minutes of unproductive conversation, I realize that the people simply had different definitions for some of the words they were using.

Think of how much time could be saved if everyone got a small glossary at the start of the meeting that they quickly scanned.

Obviously you can't know what terms everyone is going to disagree on beforehand, but at least with a book you can know what icons are being used and what they mean.
Thursday, April 17, 2003

I was in the bookstore yesterday and picked up the first book in Donald Knuth's "The Art of Computer Programming". It also has a "how to read this book" section but it differs from any other I have seen. It basically looked like a UML diagram or flow chart.

Thursday, April 17, 2003

IMO, Kyralessa's response is the correct one. wrote, "Think of how much time could be saved if everyone got a small glossary at the start of the meeting that they quickly scanned."

A Project Glossary is not a new concept. I suppose the reason most project teams don't create them can be blamed on "short-term thinking" which is so prevalent in this industry.

One Programmer's Opinion
Thursday, April 17, 2003

I am both a writer and a software engineer. I disagree that descriptions of contents are useful for inexperienced readers. I also disagree with the claims that technical people are not equipped to judge these things.

Some technical people are poor at communicating, but so are a surprising number of technical writers.

Descriptions of contents should not be needed if the text and graphics are clear. It's as simple as that. Inexperienced users actually get deterred by things like descriptions of contents. It makes the text look more involved, rather than less.

As with software, work must be done to make the text clear, rather than fiddling with irrelevancies.

Thursday, April 17, 2003

., I agree with you, but you say your self, even some technical writers aren't good communicators. Until such time as they all are, perhaps a little glossary of symbols isn't a bad thing.

My Orielly Regular Expression book had a similar section, and it was important because you need to know exactly when a regular expression started and stopped. What was plain text, what was not, etc.
Friday, April 18, 2003

On the whole I'm not interested in the furbellows and twistles that someone thinks are important in the history of bit fiddling but which have nothing to do with the depth or breadth of the main material.

If there are funny symbols and indentations and the like to make it easier to read then stick them in a table.  But then if they need sticking in a table they aren't intuitive and they'll always be a distraction.

Eschew funny symbols, use good clean layout and sentences that  have content and not regurgitated fish heads.  Oh and try not to rival Lord of the Rings in page length, spine thickness does not imply depth of content.

Use the amount of words it takes to convey your meaning, do not artifically inflate the size of the font in order to waste more paper (this is more a publisher trick than an author's) and don't treat the reader like a puddin'.

Simon Lucy
Friday, April 18, 2003

Since each computer/tech book has to stand on its own, each one has to explain all its conventions; and the Manual of Style has not yet grown a section for orthography of computer input and output.  There's a standard way to write footnotes; there isn't a standard way to set forth a compact example of how to use a command with options.  Different traditions of computer documentation use different conventions; VMS docs were different from UNIX manpages.

But published tech books suffer from a variety of deficiencies described by Phil Greenspun at
which is the story of how he got asked to write a tech book.

Daniel Boyd
Friday, April 18, 2003

The part of the Greenspun article I wanted to point to, begins with the following sentences:

Another important albeit implicit tenet is that readers are incredibly stupid. Combine that tenet with the observation that most computer book authors are incompetent and you get the "book with user interface."

Daniel Boyd
Friday, April 18, 2003

You ever heard of someone surviving a plane crash?

Those safety briefings are _real_ useful.

R. C.
Saturday, April 19, 2003

On the subject of plane security, about ten years ago I was flying back from Dehli to Riyadh.

The plane was full of Indian labourers on the way to their first job in Saudi, and for some reason they had put me in the non-smoking section (yes, for the youngsters among you, there was a time when the back of the plane was a little oasis of freedom  not yet overrun by the ant-tobacco hordes).

I asked the stewardess if it would be possible to move me, and she said she would do it after the seat belt lights came back on again. I called her again when this happened, but she said she couldn't move me because I had to say next to the emergency exit because there were only half-a-dozen of us on the plane who could read the instructions.

Stephen Jones
Saturday, April 19, 2003

Well, as a professional technical writer, I'll take a stick my neck out and make a comment.

First, technical writers are never paid by the word any more than programers are paid by lines of code. If they are, someone's doing the wrong thing in both cases.

Second, convention sections should be where the reader is shown how the style in the book map to the information they need. For example, actual commands are in bold text. Optional arguments are in italics, and screen output is in a different font.

How important this is depends on the subject matter and the reader. For example, a windows program with a simple UI may have a manual with simple conventions. On the other hand, a program requiring the use of SQL statements is going to have more complex conventions for things like syntax.

As for Bored Bystander's comment about the "unwashed proletariat"... not to pick on you, but this is typical programmer narrow-mindedness. The simple fact is most people couldn't give a sh*t how computers. And why should they? The only reason people might have to learn about how software works is because the UI designer hasn't done their job. You don't, for example, need to know anything about and internal combustion engine works in order to drive to the store.

Anyway, it's very late so I'll shut up now...

Mark Levitt
Saturday, April 19, 2003

Get over it, Stephen.  Why don't you take up chewing instead?  Because if you chew tobacco, I don't have to chew too.

I'm sick to death of smokers whining about the fact that the public has finally wised up and stopped letting them inflict their poison on all of us.  You still get to drive up health care rates for all of us; you still get to litter every intersection with your cigarette butts; you still get to stink to high heaven when you come back from smoke break.  So enjoy those freedoms and get over your burning desire to befoul the air the rest of us would like to breathe.

Saturday, April 19, 2003

*  Recent Topics

*  Fog Creek Home