PDA

View Full Version : Technical Writing/Documentation???



Melman
04-12-2006, 10:06 AM
This is stretching it, but I'm hoping we have at least a couple of people who will understand what I'm trying to find:

Are any of you involved with writing technical documentation??? I'm trying to come up with a better way of putting together our training documentation. I'm working specifically with our computer applications right now, but it could branch out into other areas. We've just been using plain old Word docs with lots of captured screen shots inserted at appropriate places.

I'm pretty sure Word can be used much more efficiently/effectively than we're doing now. I just can't figure out how to do this. I've been looking at "headings" and some other stuff, but I'm not sure I'm headed in the right direction. I also suspect that Adobe Acrobat can be used to create .pdf files. I know pretty much nothing about Acrobat other than how to take a Word doc and convert it to .pdf. I'm sure it can do lots more than that.

If any of you do this for a living, do you have any suggestions to offer? Right now, I can pretty much go whatever route I'd like. I'll gladly buy appropriate books, software, whatever. Help?!?!?

Thanks!!!

RGreen
04-12-2006, 10:44 AM
I haven't worked much with it, but it sounds like a program like QuarkXPress might be helpful for you especially since you're using so many visuals.

http://www.quark.com/products/xpress/overview.cfm

blazedog
04-12-2006, 10:49 AM
I haven't worked much with it, but it sounds like a program like QuarkXPress might be helpful for you especially since you're using so many visuals.

http://www.quark.com/products/xpress/overview.cfm

I was also going to suggest desk top publishing application which does make it significantly easier to deal with graphics since it is used to create magazines etc.

Quark might be overkill as there are now "consumer" oriented programs which don't have all the bells and whistles but simplify page layout - really depends on what your needs are but you can create text in word and then drop it into text blocks and layout is altogether simpler -- I use something called Print Shop and it also creates labels, cards and other "printing" projects.

Melman
04-12-2006, 11:09 AM
I'll check both options. Thanks so much for your responses!

These documents do have some images included, but there's an awful lot of text. Have you seen documentation that has a cover, a table of contents, and then nicely organized chapters? Almost everything I have in my possession for various applications has a similar look. They're clean...neat...and a very nice layout.

It just hit me to include the information that these are manuals that people can keep at their desks to use like user guides.

Do you think Quark, Publisher, Pagemaker (is that still the name of it) would do this? I remember using Publisher and Pagemaker more for flyers, newsletters, and smaller documents like that. I'm not familiar with Quark at all but I'll definitely check it out.

blazedog
04-12-2006, 11:12 AM
I think Word is probably your best option then as it is generally used to create "books" with TOC, Indexes etc. I was thinking you were creating something with many graphics.

You could get a Word "how to" book which would explain how to access those parts of Word that do this --

funniegrrl
04-12-2006, 11:33 AM
This is a major part of what I do for a living ...

If you really don't know all the ins and outs of Word, I highly suggest taking courses that will give you an overview of all the features. The company I used to work for, New Horizons Computer Learning Center, has branches all over the country and they offer 1-day courses at the Beg, Int, & Adv levels. I believe they even have online classes now. You may not think you need Beginning, but you'll be amazed at what you'll learn even if you've been using the program for a while. www.newhorizons.com. You could also use a book to self-teach, but I think taking a class is more efficient.

If you want to go the DTP route, I'd suggest MS Publisher, and training as well. DTP programs "think" differently than word processors, it's helpful to know the particulars. DTP programs can DEFINITELY be used to create extensive documents with lots of text, but if you are more comfortable with Word and it is doing what you want, then there's no reason not to continue to use it, and word processors do have more automated-text tools such as creating a TOC based on heading styles, etc. The downfall is that graphics handling and other display/layout tools are seriously lacking. The more complicated the layout, the less suitable word processors are.

Another good program to consider for your screen shots is SnagIt, it has a lot of built-in tools that are great for just this purpose.

Goldie
04-12-2006, 02:27 PM
I use Word at my job to create 300-800 page manuals, with chapters, indexes, etc., every day. For our company, it works very well since we can have our content providers give us source text right in Word. For the most part, I don't write the content since it's highly technical. Also, we use a LOT of tables, and Word's tables are pretty easy to use unlike some of the other page layout programs like Quark, etc.

I have used Quark and liked it as well, but have become extremely frustrated with Publisher and gave it up a long time ago. This may be a personal problem!

You'll want to learn to use styles, since you can easily create a Table of Contents using Word's built-in Heading styles:

http://www.mousetrax.com/styles.html

Also learn about headers and footers:
http://www.computorcompanion.com/LPMArticle.asp?ID=246

As far as Acrobat goes, yes it creates the PDF files, which are our preferred method of distribution since it's a universal format. And vital to use if you use Quark or some other page layout program that your readers aren't likely to have on their desktop. Acrobat will also use your built-in Heading styles to create bookmarks to make it easy to jump around the document. And you can insert cross-references in Word (e.g. 'see page xx', where xx is a field that you insert, that will update automatically as the number of pages in your document changes. Those cross-references will turn into hyperlinks in your pdf file, providing another easy way for readers to navigate your docs.

Anyway, hope this helps.

Goldie
04-12-2006, 02:43 PM
oops - duplicate post

Melman
04-12-2006, 03:22 PM
Goldie - Thanks for those links. They sound exactly like what I'm wanting to find!!

I went to an independent bookstore at lunch to look for a book on Word. They've evidently decided to drop their computer books selection. There were no more than about 8 books on the entire shelf!!! Very strange.

funniegrrl - Thanks for your information too. I'm sure taking classes would help, but I actually teach Introduction to Computers at my college. :D We don't get as far into the subject as headings and table of contents, etc., though. I think a book, along with potentially these websites, will probably help me do what I'm wanting to do. I forgot about Snag-It...I used to have that on my PC when I was in another department. I need to re-install it. Thanks for that reminder!

NancyR
04-12-2006, 05:37 PM
Goldie,
Thanks from me too for the links. I have tried to create a small publication using the "manual" style and get VERY frustrated with it. Just when I think I am winning it will put things in strange places or change things I didn't mean to change :confused: . I'm glad to know it can be done and plan to keep at it until I master it. When you do your things at work do you start with the "manual" style?
Nancy

Goldie
04-12-2006, 07:22 PM
Nancy, not sure what 'manual style' is - was that referenced in one of the articles I sent links for? If so, I can go look and let you know.

We have our own templates we created that we use for our manuals. (If you are creating books, you will also want to learn about templates and section breaks, among other things.) Templates basically contain sets of styles that you would use for your document. You need to use some of the built-in Heading 1, Heading 2, etc. styles in order to create a Table of Contents, etc., but for most other things you can (and should) create your own styles for each type of content in your document, so it looks nice and consistent.

Yes, I am familiar with Word automatically screwing things up for you :D I would recommmend you turn off pretty much all of the AutoCorrect options, unless they are some you really find helpful. They can drive you nuts otherwise.

There are also email lists if you get stuck with a problem in Word, which I use a lot and are VERY helpful when you are beating your head against a wall. The Word-MS group on Yahoo is good, and there is also a group on Microsoft's website (hope this link works):
http://www.microsoft.com/office/community/en-us/FlyoutOverview.mspx#13

These groups are indispensable when you're the Word expert in your office, and something isn't working! It's hard to remember how we got our work done without the Internet.

NancyR
04-13-2006, 08:02 AM
Hey Goldie, thanks so much for the reply. I'm sorry, I said that wrong. What I meant was that I was using the "manual" template. It comes with Word. You can load the sample manual they have created and then see examples of how each style is used. Trouble is that parts of it are confusingly written (at least to me) and not everything works the way it seems like it should. I'm not one of those people who blame Microsoft for anything....I think it is truly amazing what computers can do and after all we are trying to do a VERY complex thing here, there are bound to be problems. It does make you tear your hair out at times though :eek: .
Yep, your link to the Microsoft forum worked and I will be sure to bookmark it. I have used the forum on CNet which I find very useful too. Here is a link in case you are interested for CNEt forums (http://reviews.cnet.com/4520-7600_7-5565323-1.html) I will definitely start checking the Microsoft one too.
thanks for the help. I just might bug you the next time I get stuck.
Nancy

P.S. What version are you using? I am still with Office 2000 because nobody has ever said anything encouraging about upgrading. If anybody ever tells me they like the newer version better I might consider it.

P.P.S. To get at the "manual" style you choose File/new/publications/manual

jking323
04-13-2006, 09:26 AM
I've written a fair amount of technical material, and I usually like to use hyperlinks to connect to different parts of a huge document. Making one enourmous Word document is usually a bad idea (it gets confused with pictures and whatnot), so you can break it into smaller documents and hyperlink them all to a central table of contents. The different text styles in Word can help with that, but I personally don't like relinquishing that much control. You can also link to other file types (Powerpoint slides, for example) to keep the Word document under a little better order.

Maybe I've just restated a bunch of earlier stuff, but FWIW.

funniegrrl
04-13-2006, 10:01 AM
When using Word to make large documents, you can use the "master document" feature. This keeps it from being one honking huge file, and makes it much more manageable.

As for the templates, yes, they are great if (a) you use it EXACTLY as it is set up with absolutely no deviation or (b) you know Word at a professional level so you understand how to change the intricate settings, styles, etc. If you know just enough to be dangerous, they can be more trouble than they are worth. I have taught Word to an advanced level and I still sometimes get ensnared in their template setups.