TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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-
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-
