I need to learn how to format a technical document

[lgalluproholt]

Help! Just got a writing gig to create a technical manual, and I want
to format it correctly as I go. For the life of me I can't figure out
how to do it! End product I want is to have the TOC, with headings and
subheadings at the front of the document; when you click on the
heading, it automatically jumps to that section. TOC would list page
numbers as the document was created, be collapsible, etc.

The set up for my document will be primarily in outline form: section
heading, followed by introductory paragraph, followed by a subheadings
and their contents.

Any suggestions for books/tutorials? I'm an experienced MSW user, but
have never had occasion to use it in this way until now.
I (of course) need it quickly, so any and all advice is appreciated!

 

[Daiya Mitchell]

There is a tutorial and sample template here.
http://www.mvps.org/word/FAQs/Customization/CreateATemplatePart2.htm
(hit refresh a few times in Safari, or use a different browser)

See also:
http://www.shaunakelly.com/word/numbering/UseBuiltInHeadingStyles.html

http://word.mvps.org/FAQs/Formatting/NumberingFrontMatter.htm
(hit refresh a few times in Safari, or use a different browser)

http://www.shaunakelly.com/word/toc/CreateATOC.html

If you have never heard of using a template in Word, *start* with this link:
http://www.mvps.org/word/FAQs/Customization/CreateATemplatePart1.htm
(hit refresh a few times in Safari, or use a different browser)

If you are using outline numbering, see here:
http://www.shaunakelly.com/word/numbering/OutlineNumbering.html

But I don't think you will be able to get collapsible text in the TOC, or
not very easily--it's not a built-in feature. There's a kludge involving
macros, which I personally think is more trouble than it's worth.

 

[Tim Murray]

Help! Just got a writing gig to create a technical manual, and I want
....

Any suggestions for books/tutorials? I'm an experienced MSW user, but
have never had occasion to use it in this way until now.
I (of course) need it quickly, so any and all advice is appreciated!

Then ask them to let you use FrameMaker so you can do a REAL book!

 

[John McGhie]

Hi Tim!!

Nice to hear from the Pleistocene Era of documentation production -- where
have you been??

Long-term viewers of this family show will know that Tim and I maintain this
running battle with each other over which application is more suitable for
writing books. Tim is a FrameMaker specialist with very high ability in
Word, but he tends to favour Adobe FrameMaker.

I am a Word specialist with enough FrameMaker knowledge to keep him honest
I try to do all of my books in Word, and it's books I do for a living:
big ones, I'm a Technical Writer. I quote a higher rate if I am forced to
use FrameMaker, to cover the reduced productivity.

Which one you actually choose depends a lot on your working environment.
FrameMaker has no macros or automation, and is not good at corresponding
with other applications. Moving text in and out of FrameMaker in a
corporate environment gives you so many compatibility issues that the pain
is just not worth it.

On the other hand, FrameMaker is designed for and totally dedicated to long
document production in a professional workspace. If your application is
such that only highly-trained documentation professionals need to work on
the text, you do not give a toss about whether you can share text with
Microsoft Office, and you intend to type all of your content without using
any automation, then FrameMaker should be considered because it has high-end
text layout and typesetting functions that Word does not have.

Whereas in Word, professional work-practices such as version control, change
management and style specifications are all optional, in FrameMaker these
things are the way the product works. In a sense, you cannot avoid
"following the rules" in FrameMaker, because that's the way it works. In
Word, you have the ability to get yourself into more trouble than a
one-armed taxi-driver with the crabs if you so choose...

Most people consider that Conditional Text is the most compelling reason to
use FrameMaker. It's a built-in feature of Frame, it's complex to do it
easily in Word. Having used conditional text on either platform, many
people wish they hadn't It makes documents quite a bit more difficult
to maintain.

Cheers

Then ask them to let you use FrameMaker so you can do a REAL book!

--

Please reply to the newsgroup to maintain the thread. Please do not email
me unless I ask you to.

John McGhie <[email protected]>
Consultant Technical Writer
Sydney, Australia +61 4 1209 1410

 

[Tim Murray]

Nice to hear from the Pleistocene Era of documentation production -- where
have you been??

Long-term viewers of this family show will know that Tim and I maintain this
running battle with each other over which application is more suitable for
writing books. Tim is a FrameMaker specialist with very high ability in
Word, but he tends to favour Adobe FrameMaker.

Some day you and I will have to meet and consume mass quantities of adult
beverages over this... ;-)

 

[John McGhie [MVP - Word and Word Macintosh]]

Be careful what you wish for ...

Some day you and I will have to meet and consume mass quantities of adult
beverages over this... ;-)

--

Please reply to the newsgroup to maintain the thread. Please do not email
me unless I ask you to.

John McGhie <[email protected]>
Microsoft MVP, Word and Word for Macintosh. Consultant Technical Writer
Sydney, Australia +61 4 1209 1410