Tek-Tips is the largest IT community on the Internet today!
Members share and learn making Tek-Tips Forums the best source of peer-reviewed technical information on the Internet!
-
Congratulations TouchToneTommy on being selected by the Tek-Tips community for having the most helpful posts in the forums last week. Way to Go!
Technical Writers
- Thread starter Gramm
- Start date
RoguePoet01
Programmer
I've done it in the past.
Use plain English.
Use lots of white space.
Pictures are worth a 1000 words.
Have a peer, who is unfamiliar with the subject, sit down and try to do whatever it is you're writing about.
Use plain English.
Use lots of white space.
Pictures are worth a 1000 words.
Have a peer, who is unfamiliar with the subject, sit down and try to do whatever it is you're writing about.
Gramm
Know your audience.
Know what the ulitmate objective is, and stay on track.
Keep it simple. If you need to get complicated, the use of a reference may be appropriate.
Stay professional, but add some humour.
Try and keep your text engaging.
Use a high percentage of short sentences.
And follow the three rules...
Tell them what you are bout to tell them.
Tell them.
Then tell them what you told them.
(Summary, detail, review)
Approaching things from a procedural process is a frequent methodology. Step 1 -> Step 2...
However, the best documentation I have come across, from my perspective, is to add a bit of detail - why you need to do this, what happens if you don't, "gotcha's", hints...
Include a section on trouble shooting and FAQ's.
Finally, realize that not everyone will be able to follow you at the level of text you choose to use -- some above, some below. By organizing your documentation in an appropraite manner to allow the high level readers get to the "meat" quickly, but will allow the low level users to access to the technical info they need.
Know your audience.
Know what the ulitmate objective is, and stay on track.
Keep it simple. If you need to get complicated, the use of a reference may be appropriate.
Stay professional, but add some humour.
Try and keep your text engaging.
Use a high percentage of short sentences.
And follow the three rules...
Tell them what you are bout to tell them.
Tell them.
Then tell them what you told them.
(Summary, detail, review)
Approaching things from a procedural process is a frequent methodology. Step 1 -> Step 2...
However, the best documentation I have come across, from my perspective, is to add a bit of detail - why you need to do this, what happens if you don't, "gotcha's", hints...
Include a section on trouble shooting and FAQ's.
Finally, realize that not everyone will be able to follow you at the level of text you choose to use -- some above, some below. By organizing your documentation in an appropraite manner to allow the high level readers get to the "meat" quickly, but will allow the low level users to access to the technical info they need.
dilettante
MIS
I'd say audience awareness is a very important factor. Maybe the most important.
Usage instructions for some end-user software product (say, a timekeeping system) need to be written very differently from programmer reference documents (for example a set of in-house developed software components).
Another resource that might be useful to technical writers is all of the "writers' guides" offered by technical publications and websites. Many of these are available over the 'net, and by collecting those covering your subject domain and intended audiences you might be able to synthesize your own "bible" for technical writing.
Some examples:
Those are just a couple quick-links. I'd suggest other sources be used as well. Try IBM, Sun, SourceForge, InformIT, TechRepublic, and others. Many tech sites and magazines offer writers' guides, and some may contain real gems.
You can even find automated aids for narrow types of documentation, such as this one:
This one analyzes the actual compiled code to create standardized, skeletal documents for ActiveX projects. It has the advantage of making sure most relevant, exported methods, properties, events, enums, and so on get spelled out accurately. It also provides a consistent organization for such documents within your organization. Since the source is offered, a programmer could modify it to meet local needs and preferences too.
Then of course a writer needs to take the result and add flesh to these bones.
Usage instructions for some end-user software product (say, a timekeeping system) need to be written very differently from programmer reference documents (for example a set of in-house developed software components).
Another resource that might be useful to technical writers is all of the "writers' guides" offered by technical publications and websites. Many of these are available over the 'net, and by collecting those covering your subject domain and intended audiences you might be able to synthesize your own "bible" for technical writing.
Some examples:
Those are just a couple quick-links. I'd suggest other sources be used as well. Try IBM, Sun, SourceForge, InformIT, TechRepublic, and others. Many tech sites and magazines offer writers' guides, and some may contain real gems.
You can even find automated aids for narrow types of documentation, such as this one:
This one analyzes the actual compiled code to create standardized, skeletal documents for ActiveX projects. It has the advantage of making sure most relevant, exported methods, properties, events, enums, and so on get spelled out accurately. It also provides a consistent organization for such documents within your organization. Since the source is offered, a programmer could modify it to meet local needs and preferences too.
Then of course a writer needs to take the result and add flesh to these bones.
guestgulkan
Technical User
I've done a bit of it. I did check out the style of other technical manuals like the user handbooks you get with equipment and such to get a feel for style, layout, information etc.. (why reinvent the wheel?).
willir says add some humour - but note that if your manual is to be translated into 'foreign' languages beware that humour 'does not always travel'.
willir says add some humour - but note that if your manual is to be translated into 'foreign' languages beware that humour 'does not always travel'.
Agreed. Technical documentation isn't usually read like a novel, but browsed for information as-needed. Humor can be fun, but that defeats one of the purposes of tech writing, which is to convey as much information as possible to the reader. Humor is just another thing they have to read to get to the information they want/need.
There are many books on technical writing, the priciples of which don't change much. Keep it simple, straightforward, and use imperative voice.
There are many books on technical writing, the priciples of which don't change much. Keep it simple, straightforward, and use imperative voice.
RoguePoet01
Programmer
Concerning humor...a little is okay just so long as it's actually funny and not hammy.
Also, break all steps out into seperate lines, and sub-steps into lines under the step lines.
I just tried to install PHP on my home computer, and it was a total bear. Luckily I found some instructions on this site that got me up and running first time.
Also, break all steps out into seperate lines, and sub-steps into lines under the step lines.
I just tried to install PHP on my home computer, and it was a total bear. Luckily I found some instructions on this site that got me up and running first time.
lionelhill
Technical User
From a user's perspective:
(1) get the facts right. I get really depressed when the information is plain wrong. But usually I've already bought the book by this stage, so the publisher has already got their cash. Pity.
(2) have a look at other technical material of the nature you intend to write:
(2a) If you can find it on the shelf in your workplace, this is probably a bad sign. Someone would have nicked it if it were actually useful. Go and look next to people's computers and see if you can find something there..
(2b) Now look and see if the pages are all nice and clean with sharp corners, and if the price label is still readable on the back. This is a clear indication that the book has not been read. The best book I ever read was twice as fat at the page end as the binding end, nearly brown, and had a furry feel about it, together with coffee-stains and very round corners.
I am always amazed how many very expensive books on using a particular piece of software have obviously never been read. Generally the problem is that the people who can understand the book already know enough that they don't need to read it, while those who need to read it can't understand the way it's presented.
And I personally HATE little pictures of silly people with lightbulbs over their heads plastered in the margins ever time you want to say something important. I mean, if I can get away without reading the bits in between, why did you write them?
(1) get the facts right. I get really depressed when the information is plain wrong. But usually I've already bought the book by this stage, so the publisher has already got their cash. Pity.
(2) have a look at other technical material of the nature you intend to write:
(2a) If you can find it on the shelf in your workplace, this is probably a bad sign. Someone would have nicked it if it were actually useful. Go and look next to people's computers and see if you can find something there..
(2b) Now look and see if the pages are all nice and clean with sharp corners, and if the price label is still readable on the back. This is a clear indication that the book has not been read. The best book I ever read was twice as fat at the page end as the binding end, nearly brown, and had a furry feel about it, together with coffee-stains and very round corners.
I am always amazed how many very expensive books on using a particular piece of software have obviously never been read. Generally the problem is that the people who can understand the book already know enough that they don't need to read it, while those who need to read it can't understand the way it's presented.
And I personally HATE little pictures of silly people with lightbulbs over their heads plastered in the margins ever time you want to say something important. I mean, if I can get away without reading the bits in between, why did you write them?
guestgulkan
Technical User
lionelhill You do realise that no-one actually reads manuals 
.
There are just there to look good. The only time they might get looked at is in the last resort when everybody has had a go at fixing a problem and has made a complete dogs dinner of it.
.There are just there to look good. The only time they might get looked at is in the last resort when everybody has had a go at fixing a problem and has made a complete dogs dinner of it.
Stella740pl
Programmer
guestgulkan,
They also are very good to wash the developer's hands in case of a problem (like: "It's said clearly in the manual you shouldn't attempt to do this, so it's not my fault you didn't read it and lost your data".
You know, like they would note in the manual to a food processor, "Do not immerse in water or other liquids" and "Do not insert your body parts into openings when the blades are moving", so if you do, you cannot sue them. Or, if they were not clever enough to say some nonsense like "Do not attempt to process anything other than food", and you decided to chop steel staples, then, who knows, your stupidiness might become food processor manufacturer's problem after all.
They also are very good to wash the developer's hands in case of a problem (like: "It's said clearly in the manual you shouldn't attempt to do this, so it's not my fault you didn't read it and lost your data"
. You know, like they would note in the manual to a food processor, "Do not immerse in water or other liquids" and "Do not insert your body parts into openings when the blades are moving", so if you do, you cannot sue them. Or, if they were not clever enough to say some nonsense like "Do not attempt to process anything other than food", and you decided to chop steel staples, then, who knows, your stupidiness might become food processor manufacturer's problem after all.
lionelhill
Technical User
Yup. Curiously the games people once upon a time got it right. Things like sim city, A-train, loads of them had really nice manuals that you'd want to read just for the fun of it. So nowadays games come with some apology for a manual as a pdf file. yuk yuk yuk.
Manuals would probably get used more if they were half-way decently written, but they're not. Straightforward page numbers would help (refer to section 3.02.274.3 for details).
Also unhelpful are half-page Sceen-shots of the file menu, accompanied by text like:
"3.1.12 Opening files
The file open button is located on the menu bar, and is also accessible through the menu item 'File: open'. This option is used to open files."
But of course you are quite right. Neither manuals nor glossy computer books are written to help users.
Manuals would probably get used more if they were half-way decently written, but they're not. Straightforward page numbers would help (refer to section 3.02.274.3 for details).
Also unhelpful are half-page Sceen-shots of the file menu, accompanied by text like:
"3.1.12 Opening files
The file open button is located on the menu bar, and is also accessible through the menu item 'File: open'. This option is used to open files."
But of course you are quite right. Neither manuals nor glossy computer books are written to help users.
Gramm,
I am known in circles at work as a very good writer of technical documentation. I have done my share of Novell, Arcserve, and other documentation to help aid the team I am in as well as the end users I support.
My suggestion to you would be as several mentioned above and a couple I would add are:
1) Know the subject matter you are writing about. If you know what you are talking about, the material jumps off the page to the end-user who is following it.
2) Use alot of screen shots of what you are talking about.
3) Know the audience you are writing to.
4) Use regular english and watch the use of "Technical Jargon". We Tech people might know what Metaframe is for example, but for end users you might need to use the word they they would understand as being Metaframe since that product can be called several things. In my office I know to call Metaframe "xyz" because the end user knows it as such and not metaframe.
I found that as I grew in my IT profession, the college training in technical writing and what I mention above helped me.
I am known in circles at work as a very good writer of technical documentation. I have done my share of Novell, Arcserve, and other documentation to help aid the team I am in as well as the end users I support.
My suggestion to you would be as several mentioned above and a couple I would add are:
1) Know the subject matter you are writing about. If you know what you are talking about, the material jumps off the page to the end-user who is following it.
2) Use alot of screen shots of what you are talking about.
3) Know the audience you are writing to.
4) Use regular english and watch the use of "Technical Jargon". We Tech people might know what Metaframe is for example, but for end users you might need to use the word they they would understand as being Metaframe since that product can be called several things. In my office I know to call Metaframe "xyz" because the end user knows it as such and not metaframe.
I found that as I grew in my IT profession, the college training in technical writing and what I mention above helped me.
One thing that I've seen, is that there are two levels of reader.
There's the guy who just wants help doing a particular task.
And there's the guy who wants to know why something works the way it does.
To help the first type, you need to write a manual like:
"Account Number: Enter your account number and click enter"
To help the 2nd type, you need to write:
"Account Number: This is a number which describes an accounting storage area. It is often segmented into company, division, department, & workcenter to make rolling values up into higher level storage areas easier."
So, you need to know what type the vast majority of your users are in order to know your audience.
Chip H.
If you want to get the best response to a question, please check out FAQ222-2244 first
There's the guy who just wants help doing a particular task.
And there's the guy who wants to know why something works the way it does.
To help the first type, you need to write a manual like:
"Account Number: Enter your account number and click enter"
To help the 2nd type, you need to write:
"Account Number: This is a number which describes an accounting storage area. It is often segmented into company, division, department, & workcenter to make rolling values up into higher level storage areas easier."
So, you need to know what type the vast majority of your users are in order to know your audience.
Chip H.
If you want to get the best response to a question, please check out FAQ222-2244 first
lionelhill
Technical User
chiph is so so right about the two types of user. And techwtr is probably right about the screen shots. I am chiph's second type of reader. We really hate the first type of explanation, Especially if it's accompanied by a gratuitous screen shot of the little window that says "account number". So if you're writing for us, please please take chiph's advice.
If you use screen shots, make sure your writing doesn't end up fossilized as the software it describes continues to evolve. All users, both of chiph's types, really really hate it when they have a nice clear screen shot that shows the "Do something" button, but their screen looks subtly different and doesn't have a "Do something" button, because some bright spark has moved it into a different submenu.
If you use screen shots, make sure your writing doesn't end up fossilized as the software it describes continues to evolve. All users, both of chiph's types, really really hate it when they have a nice clear screen shot that shows the "Do something" button, but their screen looks subtly different and doesn't have a "Do something" button, because some bright spark has moved it into a different submenu.
sabrinaduncan
MIS
I would love to get into technical writing. I have five years of network-PC experience. Years ago, I worked at a magazine for about six months.
Does anyone have any suggestions on getting into technical writing? I know that I can do it because I have seen some of the junk that gets published.
Does anyone have any suggestions on getting into technical writing? I know that I can do it because I have seen some of the junk that gets published.
- Status
Similar threads
- Locked
- Question