About Janet Underwood Expertise I can answer your questions about using Microsoft Word to create technical documents, creating style guides, documentation layouts, documentation management, and getting information from difficult subject matter experts.
Experience
Past/Present clients Sprint, DST, Squibb Diagnostics, NASA, National Seminars, Fred Pryor Seminars, Humana Health Systems, Missouri Gas, Franklin Federal Savings, Resolution Trust Corporation, AT&T.
Question Hi Thank You - Wow guess I don't know how to use word!!! Amazing. I read the first part about the bucket analogy a few times and I think I got it. You cleared up a lot by pointing out the difference between Word and other applications and providing clarification examples. I would of never got it otherwise.
As for the 2nd part the "Header" versus "Heading" and generating a " Table of Contents" Yes I am confused because I did not know there was a different meaning in the words - so I am talking two things that now reading your answer may mean the same thing.
What your telling me I think is I need to fomulate the page using a template and then the format will stay consistent throughout the document. Once I pick a template then my paragragh STYLE "headings" will be consistent throughout the document.
As for Headers on different pages I am okay there.So I believe you answered two of my questions in the first answer.
So the TOC - how does that get generated? Is it purely finish the document and say apply TOC command?
Your answer leads me to another question, is WORD okay for generating these technical documents versus other applications in your opinion? As in are there any gotchas I should look out for? I am using word because I have it and I am familiar with it.
And Thanks a Lot for your answers, They really help.
-------------------------
Followup To
Question -
Hi. What is the quickest way to learn what style guides, layouts or templates are in Word. My reason is I picked up a tech writing job to reformat or create help documents on an open source software system. I imagine there is a way to have headers and footers and the table of contents etc end up in one guide ...and then I can resuse it over and over. Is there a way or a place to point me to to get this info quickly?
Right now I do one header at a time and make it level 1 or 2 or 3 and I go page by page so you can imagine the agony when things go wrong. I appreciate any help you can give me. Greg
Answer -
Hi, Gregory -- Sorry I did not see your message earlier. I'm in the middle of a move.
The quickest way to learn about the different features of Word is to use the Help files. Of course, the problem with that is that often you won't know what to look for! Therefore, I'm going to give you a quick tutorial in Word that will help you get started.
You've actually asked several questions here, and you need to understand how Word works in order for me to answer them in a way that will make sense to you.
The first thing you need to understand is that Word works differently than other word-processing programs. While you can format your text in it as you do in other word-processing programs, this is not how it was intended to be used.
This is because Word sees things in terms of objects. In most word-processing programs, the text you type can be compared to a stream. When you want to change the formatting, you manually insert a code, such as when you boldface a word or change its size.
In Word, these formatting features (boldfacing, size, font, etc.) are objects. You define a bunch of these objects to define a certain paragraph object, such as a body text object or a heading 1 object. These compilations of formatting objects are called paragraph styles. Think of a paragraph style as a bucket into which you put all of the formatting objects that define it. When you look at your styles list (if you don't know how to find this, you need to tell me which version of Word you are using so I can direct you to it), you'll see names like "Normal," "List Bullet," "Body Text," etc.
You need to try out these paragraph styles and use them in your document to take full advantage of Word's many features. This also will help prevent your document from becoming corrupted.
Also, you need to understand that whenever you start typing in Word, you are using a paragraph style. It is called the Normal paragraph style.
Now, just as you always must use paragraph styles in Word, you also always must use a template. When you open a new blank document, say, by clicking the New button on your toolbar, that document has the Normal template applied to it. There are many templates that come with Word, such as the Fax and Letter templates.
To carry the bucket analogy on, think of your template as being an even bigger bucket. In this bucket are all of the paragraph styles for this particular type of document, as well as any macros, autotext, and boilerplate you might have added.
A template always has a .dot extension and is saved in a special folder. To find out where your templates are stored, click Tools>Options and then click the File Locations tab. Look at where it says the User Templates are stored.
You can create a template in one of two ways. You can modify an existing template, saving it with a new name and a "Save As" type as a template, or you can save an existing document as a template (click File>Save as, give it a name and select "Template" as the Save As type).
Just as you'll have greater success if you use paragraph styles rather than manually formatting your text, you'll have greater success if you use templates when writing your technical documentation.
Now, because this is getting a little long, I'm going to send it and then address your questions about headers and footers, and TOCs in another message. I'm giving you the "dime tour" of Word here, Gregory, so please feel free to ask questions about things that are not clear to you. Using Word to its full potential requires thinking about your document in a different way. Most people have a little trouble wrapping their minds around it at first!
Janet
Regarding headers and footers and the table of contents... Let's make sure we're both talking about the same thing. The header is the text that is at the very top of the page. It is the same on each page, or it can be different on odd and even pages. Within a section of a Word document, however, they are always the same.
The reason for my confusion is that when you say you are making your headers level 1 or 2 or 3, I assume that you are talking about Heading 1, 2 or 3 paragraph styles. Is that correct? If so, there is a difference between a header and a heading. Heading text are like headlines in your document. For example, you might have a level 1 heading that says "Introduction" and then under that, have a level 2 heading that says "Overview."
Because heading styles are closely related to generating a table of contents, I think we probably should clear up what you are wanting to achieve before going further. Do you mean headings or headers in this context?
Janet
Answer I'm glad this is helping, Gregory. As I mentioned in the previous message, it takes a bit of getting used to, so be patient with yourself! Once everything "clicks," it will be much easier!
To answer your last question first, Word is not the application that technical writers think is the very best to write technical documention. That is because Word gets a bit dicey with very large documents, and many technical documents are very large and have many graphics that inflate the size of the file. Because of this, most technical writers prefer to use Adobe's FrameMaker, which was designed to handle large documents with more stability. The problem is that FrameMaker is very expensive and have a high learning curve. Also, you cannot share your files as easily as you can your Word files. That is the reason why, even though it is not preferred, Word is the most commonly used application to write technical documents. The fact that 93% of all companies around the world use Word also factors into this.
That being said, it behooves technical writers to become masters at using Word and understand how to keep their documents as stable as possible. Using paragraph styles and avoiding manual formatting as much as possible is the No. 1 way to do this (keep documents stable). You don't have to use every paragraph style available in Word. In fact, I generally use no more than 10 paragraph styles in any given document -- the Normal paragraph style, Headings 1, 2 and 3 paragraph styles, the Header and Footer paragraph styles, and some that I define myself, such as a Table Text paragraph style, generally are the major ones that I apply consciously. Many paragraph styles, such as the TOC ones and the Caption paragraph style, are applied automatically when you use specific features (for example, when you generate a table of contents, the TOC paragraph styles are applied to each line, and when you add a Caption -- Insert>Caption -- the Caption paragraph style is applied to your caption automatically).
Let's talk more about the table of contents. I'd like for you to look at the dialog box that you use to generate the table of contents. If you are using Word XP, click Insert>Reference>Index and Tables on your menu bar, and then click the Table of Contents tab. If you are using Word 2000 or an earlier version of Word, you just need to click Insert>Index and Tables to get to the same dialog box.
On the Table of Contents tab, look at the Print Preview. It probably says something like this:
Heading 1 (perhaps in a larger type size)...........1
Heading 2 .......................................3
Heading 3.....................................5
(Note: I'm not sure that my indents will show up in this message, but Heading 2 is indented under Heading 1, and Heading 3 is indented under Heading 2.)
Text that has these heading styles applied to them will be picked up for the table of contents when you generate it. For example, let's say that you have a document that has this on the first page:
1. Introduction (Heading 1 paragraph style)
1.1 Overview (Heading 2 paragraph style)
Text about the overview with the Normal paragraph style applied to it would come here.
1.1.1 Further Explanation (Heading 3 paragraph style)
Text about the further explanation with the Normal paragraph style applied to it would come here.
If you generated a table of contents at this point, showing 3 levels in your table of contents (you select how many levels you want on the Table of Contents tab), it would look like this (remember that all of this is on page 1 of your document):
1. Introduction.......................................1
1.1 Overview.......................................1
1.1.1 Further Explanation......................1
Word is going to generate the table of contents by picking up only these three heading styles, and it will display the text that has these styles applied to it.
Now, I'd like for you to click the Options button on the Table of Contents tab. The Table of Contents Options dialog box opens. Notice that it says, "Build Table of Contents From:", and unless you have changed it, there is a checkmark in front of the word "Styles." This is saying that Word is going to build your table of contents from paragraph styles. Beneath that, it shows you the paragraph styles that are available in this document for you to use to build your table of contents. To the right, it says "TOC Levels." Since you are using 3 levels in your table of contents, you want any of the styles that you use to be either a 1, 2 or a 3. This will affect how they are formatted within your table of contents. You can select any paragraph style to be picked up by Word for the Table of Contents, by the way. You don't always have to use the Heading paragraph styles. I often create a new paragraph style for Appendix Headings, and use the Table of Contents Options box to designate that I want these headings to be level 1 in my table of contents.
Remember, using paragraph styles is the key to using Word successfully in technical documentation. A little tidbit of information that is important to know is that all of the definitions of a paragraph style (typeface, size, etc), are "held" in the paragraph mark that is inserted when you press ENTER. You may not see this all of the time because it is hidden, but it's important to know about this because if you accidentally delete a paragraph mark and the paragraph that follows the one where you deleted that mark is a different style, you will change the style of the paragraph. It's easy to fix (press Enter to insert the paragraph mark again, and then reapply the style that you want), but it can be a headache.
You asked about "got'cha's" in Word. There are many lurking there for the unwary! For example, manually formatting your text -- especially if you have heading, bullet or list paragraph styles applied to that text -- can easily corrupt your document. If you've ever had a document become corrupted, you know it's not a pretty sight. First, you'll get a message saying the document is corrupted whenever you open the document (this happens a lot when people use documents as templates, by the way). You might ignore that message because it seems like nothing is wrong. You might even continue without doing anything about it for several weeks or even months! Then one day, usually when it is most inconvenient, it happens. You delete one paragraph mark because you decided to move a paragraph or delete it all together, and WHAM! all of a sudden, you have no more headings in your document and the numbering is all skewed. Most often, all of the text in your document suddenly is 8 pt. Times Roman bold. Do you know how hard that is to read?
That's why I stress so much that you learn more about paragraph styles and even more importantly, use them in your document. If you want a level one heading, use the Heading 1 paragraph style. If you are typing body text, use the Normal paragraph style or the Body Text paragraph style.
I'd really like to talk with you more about the Heading paragraph styles and using outline numbering with them, but if you don't mind, let's save that for another message, okay? These styles can be twitchy.
For now, here is another got'cha's to watch out for:
1. Putting a table in your document that breaks over several pages, and designating in the Table Properties box (Tables>Table Properties>Row tab) that rows can break across pages while designating in the Paragraph dialog box (Format>Paragraph>Line and Page Breaks tab) that you want to keep lines together. This one can get really ugly. What happens is that at a certain point, Word starts repaginating the pages. At first, you think it's just going through the automatic repagination, and then you notice by looking at the status bar that it is on page 2008 of your document and still generating pages--and your original document only had 50 pages the last time you looked at it! What makes this so ugly is that it can blow out your swap file on your operating system. Get out of this as soon as possible -- even if it means powering off your computer without going through shutdown. (Which you often have to do because while Word is repaginating your document, it won't let you close it.) The fix? Remove the checkmark in front of the "Keep Lines Together option on the Paragraph dialog box.
When we talk more about heading styles, I'll share some more things like this with you. Let me know if you have questions about what we have discussed so far.
