RE: Framemaker, Word and Robohelp

Subject: RE: Framemaker, Word and Robohelp
From: Chris Gooch <Chris -at- lightwork -dot- co -dot- uk>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 18 Jan 2001 14:48:06 -0000


John Gilger wrote:

Wouldn't it make more sense to have the members of the writing team
who are
best developers of content (writers) use simpler software such as
Wordpad,
vi, or (my personal favorite cyber-swiss-army-knife) emacs to write
in text
files and having one or two of your best layout gurus using a good
type
setting, markup, or layout program (TeX, SGML, Framemaker, Word ...)
format
the stuff and make it look pretty?

Apologies for coming in a bit late on this thread... a combination of time
zones,
being in digest mode, and workload :-)

My own perspective as the only (currently) writer at a software company is
that I rely
on my SMEs (software developers) to write quite a lot text which I can then
edit.
This is especially so for some more straightforward parts of the
documentation
(for example a page of technical documentation for each API in our product
is
required).

I have them do this in plain text form (some send me ascii - some use Word,
which
I then convert to ascii). I then edit/re-write as necessary, and typeset
using LaTeX.

Doing things this way provides several advantages;

1) There is no learning overhead for the SMEs to use as a reason not to
provide me with source material

2) There is no cost overhead to the SMEs providing me with source
material
(in terms of FrameMaker or god forbid Robohelp licences this is not
insubstantial to a small company with a large number of developers).

3) I don't have to undo the bad or non standard formatting that would
otherwise result.

4) I can concentrate on editing and improving the material I am giving,
and writing new / extra material where it is required.

5) I also retain control of indexing, cross referencing, and version
control,
without this being a constraint on my SMEs doing some writing for
me.

To my way of thinking (which I admit is influenced by the fact that I am a
LaTeX
devotee), there is and should be a clear distinction between writing clearly
and
presenting (in the case of printed information this means typesetting) that
writing. Using a mark-up system such as LaTeX or SGML forces you to think
of
good writing being a case of organising things logically --- the visual
appearance
should be simpy a function of the logical structure, and therefore can be
left
to the computer (with a human checking and tweaking the results where
necessary).
Once you have good quality style files, you should trust the layout to flow
from
the logical structure.

Of course there are some aspects, such as design of tables and diagrams,
where a visual approach is necessary. I simply encourage my SMEs to
present such information as simply and clearly as possible using whatever
tool(s) they are comfortable with --- I then re-work as necessary (it isn't
always
necessary).

This approach seems to have been working quite well for us for a while now,
and it's a model that's served book publishing well for (hundreds of) years.
My SMEs are happy in that they have no obstacles placed in their path,
and see nice results (their text, nicely typeset, proofed, indexed, etc.
in a nice book) at the end of the day, and therefore see the benefit of
providing
me with source material -- making my job much easier.

Just my 2 new pence's worth. The software I document by the way is
software programming toolkit stuff rather than end-user GUI stuff, by the
way, which does make a difference.

Christopher Gooch, Technical Author,
LightWork Design Ltd., Sheffield, England.

chris -at- lightwork -dot- co -dot- uk www.lightwork.com




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17)
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by DigiPub Solutions Corp, producers of PDF 2001
Conference East, June 4-5, Baltimore/Washington D.C. area.
http://www.pdfconference.com or toll-free 877/278-2131.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


Previous by Author: RE: Adobe index bookmarks??
Next by Author: RE: Source Code Documentation Systems?
Previous by Thread: Re: Framemaker, Word and Robohelp
Next by Thread: RE: Framemaker, Word and Robohelp


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


Sponsored Ads