How to write User Manuals?
I know my question has not a lot to do with the Mac, but you guys seem to be able to help with everything. If I had to nurse a rhino or change a 747's tire, I'd ask you...
I have to write user manuals for software products (Document Archive Server). As an engineer, I lack the background in technical writing. I know there exists an IEEE Standard 1063, but I was looking for something more userfriendly (readerfriendly). Do any of you guys have experience in this field? Do you know a place where I can find document templates, howtos, etc? Any personal tipps?
Unfortunately, I have to write in Word (it's an M$ world out there), and googling did not provide me with any helpful insights. Therefore, any help is appreciated. And propably you've nothing better to do while waiting for the iPhone anyway
I have to write user manuals for software products (Document Archive Server). As an engineer, I lack the background in technical writing. I know there exists an IEEE Standard 1063, but I was looking for something more userfriendly (readerfriendly). Do any of you guys have experience in this field? Do you know a place where I can find document templates, howtos, etc? Any personal tipps?
Unfortunately, I have to write in Word (it's an M$ world out there), and googling did not provide me with any helpful insights. Therefore, any help is appreciated. And propably you've nothing better to do while waiting for the iPhone anyway
Comments
Creating Passionate Users - the main writer of this blog, Kathy Sierra, used to write documentation for Sun and has since started a really successful line of programming books. Not all of her posts are relevant, but some of them are, particularly the ones about the way people tend to think. I recommend this one: http://headrush.typepad.com/creating...rketing_s.html
Also, while the book itself isn't directly related to technical writing (though I suspect it would be useful), here's some sample chapters from the first edition of Don't Make Me Think. Steve Krug also used to write documentation, and it really shows in this book. It's just an excellent example of clear, succinct communication.
As for the layout, use a simple san-serif font like Helvetica, Myriad if you have it, or Arial if you have to. Set the line spacing to around 1.5x. Set your margins to be huge on one side. 7-8 inches is too wide to comfortably read text?your eyes have to work too hard to follow the line that far. 4-5 inch wide text is both more inviting and far easier and faster to read. The extra white space also makes your product look and feel high class. It also may drive your boss nuts if he's not particularly design-oriented.
Be very careful of long paragraphs?each paragraph should be a single idea. It's better to have even just a single sentence be it's own paragraph, if need be, and let it stand out as a distinct point then to muddy it with another idea.
Make sure to use clear, precise English. Don't use difficult vocabulary. You will need to use some jargon, however, just be sure to carefully define every term. Don't be afraid to sound condescending, and make sure to define even what you think are basic, basic concepts.
As for structure, you should have three main sections. First up is a really succinct quick start guide so that people can use your product right away.
Then you need to lay down the general ideas and concepts of your application without getting into too much specifics (for example, Macintosh has files, that you put into folders, that you run in applications. Files represent your data, and you do stuff with them in applications). Try to get some diagrams in here.
Finally, you need to reference, in depth, every feature in the program. Try to group these in a logical order, clustering similar tasks together, and putting more advanced tasks towards the end of the manual.
You probably also want to add in a few tutorials (in addition to any you have in the quick start guide) that go into the more advanced concepts.
Anyway, sorry if this seems complicated. Writing good documentation is deceptively difficult. Good luck!
I know my question has not a lot to do with the Mac, but you guys seem to be able to help with everything. If I had to nurse a rhino or change a 747's tire, I'd ask you...
I have to write user manuals for software products (Document Archive Server). As an engineer, I lack the background in technical writing. I know there exists an IEEE Standard 1063, but I was looking for something more userfriendly (readerfriendly). Do any of you guys have experience in this field? Do you know a place where I can find document templates, howtos, etc? Any personal tipps?
Unfortunately, I have to write in Word (it's an M$ world out there), and googling did not provide me with any helpful insights. Therefore, any help is appreciated. And propably you've nothing better to do while waiting for the iPhone anyway
That's interesting; I like to know what you find out about that, I've been looking at an XML-based publishing system.
In all likelihood, you need to get a 'Schema' file, and use Word's XML feature [tell Word what XML schema you're using] to write your document. If that is the case -- if 'they' are feeding this to a content management system -- except for character formatting, bold, underline, etc., it probably won't matter how you format the document. All they will need from you is to apply the correct 'styles' to the paragraphs, those styles will actually structure the document when it comes time to be referenced, have XSL transforms applied, and run through an XSLFO rendering enginge (an XML-based page layout specification.)
If you aren't being asked to do all of that, it probably still doesn't matter how you format your document (within reason), they might have someone else in-house, do that for you.
As how to properly write, go to Amazon and get yourself a copy of The Chicago Manual of Style.
(But if you are writing about the Document Archive Server and not on a document archive server, I'm probably completely wrong on that first part.)
Do any of you guys have experience in this field? Do you know a place where I can find document templates, howtos, etc? Any personal tipps?
One of the reasons I got my undergraduate degree in literature instead of writing was to avoid having to take business and technical writing.
But good luck!
A lot of people I know have jobs right out of college doing just that.
The Handbook of Technical Writing
Technical Communication
Elements of Technical Writing
There are a couple of texts she uses for her advanced classes that I can't remember, but I know I've heard these names above before.
I'll see if I can get her to chime in.
Cheers
Apple Style Guide - an internal document that they also give to developers, but gives a lot of notes specifically related to computer writing.
...
Anyway, sorry if this seems complicated. Writing good documentation is deceptively difficult. Good luck!
Thanks a lot for the info. I forgot to look at Apple, of course they know the business...
I'll look at the other as well, I already own Steve Kruge's book from a previous job. I already heard about the Chicago Manual of Style, but since I have to write in German, I'll just give it a glance.
I'll get back with more info here, as I learn
That's interesting; I like to know what you find out about that, I've been looking at an XML-based publishing system.
...
(But if you are writing about the Document Archive Server and not on a document archive server, I'm probably completely wrong on that first part.)
Have a look at DocBook, it's an XML based documentation standard.
Sorry if I wasn't clear, I have to write about a document archive system, not on one (altough I will archive my work on it, of course).
We have a designer that takes care of the design, I'm more interested in the structure of a manual.
http://portal.acm.org/citation.cfm?doid=105783.105788
http://www.csc.calpoly.edu/~dbutler/...ter96/manuals/
http://www.asktog.com/columns/017ManualWriting.html
http://www.klariti.com/technical-wri...Tutorial.shtml
he mentioned that he's writing for Germans? Germans actually *read* the manual so ... he needs to be aware of that. Also ... he needs to go through usability testing t o make sure his translated instructions are usable for his audience.
It's actually pretty difficult to write a good software manual. When Im done writing a program, its hard for me to realize what is difficult and what is not.
This might suggest that coders and engineers are unsuited to write the manual for an app intended to be used by the general public, the vast majority of whom are neither coders nor engineers.
This might suggest that coders and engineers are unsuited to write the manual for an app intended to be used by the general public, the vast majority of whom are neither coders nor engineers.
True. Altough I'm an engineer, I did not code the software. I'm responsible for user projects (customization, hooking up to other systems, etc), therefore I have quite a users perspective.
Thanks for all the info so far, I'll keep you updated on my progress.
True. Altough I'm an engineer, I did not code the software. I'm responsible for user projects (customization, hooking up to other systems, etc), therefore I have quite a users perspective.
Thanks for all the info so far, I'll keep you updated on my progress.
Not to be shitty, but I thought I'd point out that in three sentences you have
1 spelling error
1 possessive error
2 comma splices
2 missing punctuation
My point is that it is a damned shame that tech writers are the first to go when companies start to tighten their belts. They tend to saddle engineers with the task of writing documentation, and while there are certainly engineers who can write excellent documentation (e.g. Dean Allen, Kevin Fox, John Gruber), by and large, they are not the best choices for such jobs—nor should they be expected to both code and write documentation.
Not to be shitty, but I thought I'd point out that in three sentences you have
1 spelling error
1 possessive error
2 comma splices
2 missing punctuation
My point is that it is a damned shame that tech writers are the first to go when companies start to tighten their belts. They tend to saddle engineers with the task of writing documentation, and while there are certainly engineers who can write excellent documentation (e.g. Dean Allen, Kevin Fox, John Gruber), by and large, they are not the best choices for such jobs?nor should they be expected to both code and write documentation.
I know my English is not perfect. As I mentioned above, I have to write the documentation in German, which is my native language. So no need to worry...