Why are so many technical manuals so poorly written?

[Nick_Jinn]

I guess we cant all be good at everything. People who are more mathematically oriented are often not as linguistically gifted. I am more of a creative type personally, and while my spelling and grimmer isnt flawless I probably have more linguistic and artistic talent.


Anyway...I notice that with a lot of technical manuals, they often start off simple and straightforward, but when they get into the details they kind of lose it. They stop breaking things down, or break some things down a little too much to the point of needless repitition, while other sections leave people scratching their head due to poor explanations. They might start using terms that they have not defined, talk about tools that they have not described, just assume that people are already aware of mid level terms and skills while describing novice level instructions. Manuals are not very succinct, tend not to hold peoples interest, lose people even during step by step instructions, overwhelm people, bore people, and are obviously written by techniques and not professional writters.

I almost think that techies should be the LAST people to write manuals teaching noobs how to use computers, unless you find a rare individual who is also linguistically talented.

My old math teacher Mr Davidson, who was a real trip btw, used to tell me that people who are good at math make the worst math tutors and teachers. Math textbooks are written by people who are good at math, not by people who are good at explaining things. I think the same thing is true when it comes to techie manuas.

The Ubuntu unleashed manual isnt the worst actually. Its better than a lot out there, besides a few sections. Still, it feels like some of the intro stuff like setting the date and time and changing the colors and themes drags on and on when its really incredibly simple when you dont over complicate it. Other parts however suddenly cover a lot of complex information all at once and might lose people......its better than most though.


Maybe what should happen is that when a techie writes a manual he/she should hand it over to someone who is actually a writer and they should entirely rewrite the entire thing while covering the same points....the authors should have some basic computer skills, but perhaps should not be experts because experts cant understand why people are having trouble understanding key concepts while someone who is perhaps not an expert understands exactly what kind of hurdles people might be dealing with.

Afternoon rant.

[oldsoundguy]

most manuals are written assuming you have a basic knowledge of the subject and of basic terms.

A FEW exceptions in the computer area.
Dell has a collection of manuals for their products that are meant to be used by granny on her first computer. MORE explanation than needed for someone that has some experience with computers, but Dell assumes that the computer you bought from them is your first computer.

Much can be said about that approach.

Software, on the other hand can be the good, the bad and the ugly when it comes to manuals. And some software is complicated out of the box. Adobe is noted for that .. too complex to begin with for a newbie!

The basic Ubuntu guide falls into the easy category provided you actually READ it. And provided you are not looking for serious problem solving. But you still have to be conversant with basic terminology.

[nothingspecial]

Try
man bash

[jetsam]

Well, for one thing, the material is often not intrinsically interesting, so it's hard to attract and keep the attention of dedicated writers.

There are good tech manuals, and there are some very good books on programming and computer science out there, but a lot of the stuff is expected to last maybe a year or two on the market and then be updated to the next edition. Plus, with so many details involved, it's no wonder that a lot of manuals end up being shallow re-writes of other manuals or the original documentation.

Tech manuals could use a longer development process. In particular, they could run beginner's guides through testers that aren't familiar with the material. Unfortunately, that would add to the cost, so I don't think many publishers would go for it. I'm sure the same kind of cost consideration prevents the literary author plus tech author co-authorship that you describe.

As for math books: I nearly collect the things, and it is very rare for a book to be both mathematically in-depth and well written at the same time. Kind of perversely, the math text books, which often are written by multiple authors and do have previous testing by students, are often the worst books to read.

[jrusso2]

Technical people have a hard time explaining things in terms regular users can understand.

Things like the man pages in Linux are extemly pooly written often I just need an example of the syntax for a command and its not even in the man page.

[McRat]

Here's the problem with the Company making their own software docs, and why aftermarket books are usually better:

The guy who really knows how it works is busy programming, so makes docs brief. Often he does not always know how the finished interface is going to look when he's writing doc notes.

Then they hire someone in charge of user docs, and they don't use the product at a serious level. They are often "creative writers" who like to use buzzwords like "the user experience" or "rich content" instead of listing items. They are often an extension of the sales dept.

So you get a manual full of "super simple" with bursts of "WTF???" mixed in (when the doc writer doesn't really understand the programmer's notes and wings it).

The best person to write a user's manual is actually a new user. Eng'g or Marketing majors need not apply.

[BobvanderPoel]

Since you are ranting, can I be sarcastic and ask what project you are volunteering to write a manual for?

It's hard to write software.

It's hard to write docs.

It's harder to do both.

Still harder is for a software writer to get someone else to write a manual for his/her project ... esp. for free.

One example of GOOD docs goes back to the manuals for Epson FX-80 printers. I think this was in the 1970s. Great manuals ... nothing better since :) I think that is when they decided that the money spent hiring a good writer could be used as profits.

[Nick_Jinn]

most manuals are written assuming you have a basic knowledge of the subject and of basic terms.

1. If so, then why go over REALLY basic concepts if they expect more than basic understanding to begin with?

2. If so, then where are people who dont have that basic knowledge supposed to begin?

3. Wouldnt that mean that people who tell noobs to read the manual instead of answering their questions be in the wrong if the manuals are not intended for noobs?

4. Even if they expect basic knowledge, they are still often poorly written, having an inconsistent learning curve, skipping steps or descriptions of steps, not providing good 'how to' for those steps, and basically lacking linguistic talent despite overwhelming technical knowledge.



Ubuntu Unleashed is surprisingly good for a manual compared to others I have seen, though I think some minor improvements could be made. The authors should be a little proud of that.

In general though, techie manuals are not the best place for noobs to learn how to do something.

[matthew]

In real life, I'm a technical writer. Good technical writing is hard for many reasons. First, the writer needs to understand the material well. Second, he needs to understand his audience and focus his writing consistently on communicating directly to that audience. Third, she needs to have a solid grasp of the mechanics of the language being used to write the material. Fourth, he must be able to break down complex ideas into simpler components and define or discuss those components with clarity and precision.

It is extremely rare to find someone who can do all of these and is also given the time necessary to do them well.


Ubuntu Unleashed is surprisingly good for a manual compared to others I have seen, though I think some minor improvements could be made. The authors should be a little proud of that.

Thank you. I am one of the authors. I rewrote chapter four this morning and am in the process of a major revision to be released before the end of the year.

[tgalati4]

Some people learn by seeing. Others by hearing, and yet others by doing. So if you bought a new printer and you pull it out of the box the following should be found:

1) A giant poster quick start-guide--no words just pictures on how to hook up the printer.

2) An electronic tutorial on CD that autoruns showing a video that verbally explains how to hook up the printer. Of course this only works on Windows.

3) A telephone book-sized manual (PDF) on the CD. The manual would be more expensive to print than the printer itself. And the printer doesn't have enough ink/toner to print it out anyway.

4) A small gnome should jump out and hook it up for you.

So one of the 4 techniques should get you up and running.

Until you discover that Canon doesn't support linux and your printer doesn't work. Then you simply pack it up and take it back and get a Kodak printer.

To me, documentation is just one barrier to overcome getting your computing environment set up. I find the forums are better/quicker for finding the information you need than any printed/published guide.

[ubunterooster]

Jetsam said it right.

Writers want to finish the programing and get on to the next program; the manual is the distraction that takes a while. So they hire another guy, except this guy likely did not help in the writing and can only relay what he himself found