RE: What Program Do You Use for Software Documentation?

Subject: RE: What Program Do You Use for Software Documentation?
From: "Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com>
To: <quills -at- airmail -dot- net>, "Paul Weir" <Pweir -at- bju -dot- edu>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 22 Oct 2008 15:42:29 -0700

A hammer is a fine tool for smashing your thumb, but it stinks for
authoring documents that call for sophisticated single sourcing and
reuse. Similarly, Word is a great tool for some ends. So is FrameMaker.
However, neither Word nor FrameMaker facilitate sophisticated single
sourcing or reuse ("snippets"). If you don't need those things,
fantastic. Word or FrameMaker may be just the ticket; if you do, you'll
want to avoid both Word and FrameMaker and look to H&M, Flare, RoboHelp
or AuthorIt.

Leonard

-----Original Message-----
From: techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- c
om] On Behalf Of quills -at- airmail -dot- net
Sent: Wednesday, October 22, 2008 2:31 PM
To: Paul Weir; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: What Program Do You Use for Software Documentation?

Most people agree that Word, in any incarnation isn't the choice if
your documents are large, complex, need strict adherence to styles,
fast editing capability or flexibility.

For short documents without intense use of cross-references,
variables to standardize phrases, tables of content, indices, lists
of tables, figures or what have you, then Word isn't bad. Once you go
over a few pages or someone want's your final document to have
hypertext cross-references, then you need a more capable program.

Adobe FrameMaker. It has more capability than does Word. It also
comes with Adobe Acrobat bundled with it. It is capable of producing
structured SGML or XML should you want that.

You didn't say what kind of documentation. Help or manuals? If you
are producing PDF, then FrameMaker is very well integrated with
Acrobat to do that.

I would also recommend using comment enabled PDF for reviews.

As for structured documents (XML) you will need a lot of effort and
education before even starting on XML. It has long-term benefits, one
of which is the ability to transform it into other formats, HTML
being one of those formats.

It's not a simple answer because your question isn't really that
simple. Given my preferences, I'd use FrameMaker for any
documentation effort as the source tool. Yes, it's that good.

Scott



At 1:22 PM -0400 10/22/08, Paul Weir wrote:
>I just started working as a Technical Writer a couple months ago and
>have been using Microsoft Word thus far to write user-documentation
>for a couple of in-house software programs. I have also recently
>been interested in learning more about using XML for this purpose,
>but am not sure it would be a benefit to me in my small IT
>department.
>
>So, I ask as a novice, what software do you all use for your
>technical writing and why?
>
>Sincerely,
>Paul Weir
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ComponentOne Doc-To-Help 2009 is your all-in-one authoring and
publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals.
http://www.doctohelp.com

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as
Leonard -dot- Porrello -at- soleratec -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit
http://lists.techwr-l.com/mailman/options/techwr-l/leonard.porrello%40so
leratec.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals.
http://www.doctohelp.com

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

References:
What Program Do You Use for Software Documentation?: From: Paul Weir
Re: What Program Do You Use for Software Documentation?: From: quills

Previous by Author: RE: What Program Do You Use for Software Documentation?
Next by Author: RE: What Program Do You Use for Software Documentation?
Previous by Thread: Re: What Program Do You Use for Software Documentation?
Next by Thread: RE: What Program Do You Use for Software Documentation?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads