RE: Technical Documentation solutions?

Subject: RE: Technical Documentation solutions?
From: "Manley Clifford (GFD1CEM)" <GFD1CEM -at- ups -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 26 Aug 2002 15:43:31 -0400

Sean & Goober - Excellent! Thanks for taking the time to discuss this.

> The R&D tech writing team and engineers in Danbury used to use Frame on
UNIX and Mac, so >
> maybe some FrameMaker still exists.

I am a newbie contractor here - is this a reference to a UPS team? I will
ask my boss as well.

> Powerpoint is an issue. IMO, it's a dead-end that narrows your choices.
Can you deliver HTML
> or PDF presentations, instead?

Yes - I think can get them to do .pdf, if you are suggesting they can create
the artifact in Powerpoint and save it as a pdf - then yeah, they would have
no problem with that.

>FM and sharepoint was discussed on the Adobe User to User forums today,
>, checkout the FrameMaker and FrameMaker + SGML


>Each TOC item could be a topic without XML; that's a traditional WWP Pro
approach with
>FrameMaker. FWIW, if your traditional user guides, with screen captures and
steps, are never
>up to date, your problem is with resource planning and management more than
it is with tools
>like MS Word. If you do not get a handle on these issues, you'll continue
to have them in a
>FM+WWP or database environment.

I really think the issue is with frustration here; we have a web repository,
but to find a doc you have to search for a document number or words in the
title or topic - and that sometimes hard to predict if you didn't write the
doc. I am thinking SharePoint so we can search for any word or phrase
anywhere in the doc, and so that we can start building some dynamic docs,
kept on our server, and just put a link on the corporate web.

>Master docs is broken. Visio has issues with PDF/PostScript output. Etc.
Before you move
>forward, I'd check whether management will give up their familiarity and
comfort with
>Microsoft's generalist office toolset.

I would suppose that FM7 and WWP would be huge change - and since I am on a
six-month contract the solution has to be both something we can implement in
that time AND they can support when I am gone.

>And, don't forget, some of this has to do with what your deliverables are.
You mention a bunch
>of guides and the like without ever telling how they are delivered, such as
PDF online only, >>as HTML, printed CMYK from an offset press, etc. Are you,
yourself, comfortable with
>producing and publishing this documentation, or are you removed from that
end process?

Laser-prints and online primarily; I am trying to make our docs as dynamic
as possible, so I want to look at "building" docs more than writing them,
and presenting them online. To me a static or printed doc is worthless - as
it is outdated within hours and therefore can't be trusted.

>I see bunches of mixed signals here . . ..

No kidding! I only have a vague idea where I want to go; accurate, current
online docs that my people will want to take the time to update - how to get
there I haven't a clue!


Thanks, man! Your ideas and comments really help.

>From: Goober [mailto:techcommgoober -at- yahoo -dot- com]
>Sent: Monday, August 26, 2002 3:13 PM
>To: GFD1CEM -at- ups -dot- com; TECHWR-L
>Subject: Re: Technical Documentation solutions?

>Dude... Stop, breathe, and think. You didn't mention deliverables. What are
you producing, and
>how are they shipped? Work backward from there, well, actually... Start
with your users' >
>needs, compare them to what you deliver to them now and see if needs are
being met Note what
>works and what does not. Note solutions. List all deliverables needed. THEN
work backward.

I pretty much have the deliverables nailed - we know who needs what, when
and how.
And, we have a team workflow that takes us through the write/edit/publish
loop pretty well
And it's pretty workable.

Where we have the real issues in in the create phase - we create static docs
for darn near everything, and they get distributed over numkerous disks,
systems, hardcopies - they're everywhere and you got no idea which is
current, so yes - it's a people issue more than anything. I have to promote
the idea that there can only be one source - that a copy saved on a local
drive or a hardcopy is extremely limited in it's validity. This is an issue
all organizations face - documents tend to live forever. I can't speak for
the company - but this ten-person team digs the dynamic single-source
concepts and I think it will work for us...soon as I figure out how,

I want to build, wherever possible, dynamic docs - built rather than written
- so that a coder changing a program only has to edit his comments and the
system (XML Parser?) picks up those comments - the documentation will always
be as current as his commentary.

Same with any other doc - instead of writing a table with multiple columns,
populating each column by typing in values, I want each column to go to the
data source and read what's current at build time - again, the doc is
dynamic and always current.

The only reason I mention tools at all is that some will and some won't
allow the kind of paradigm I envision - and I have no desire to build a
process for which no tool available to me offers support...I think it
prudent therefore to state upfront that I want to do as much of this as is
possible with Microstuff Sharepoint Team Services and Portal Server, and if
it can't be done with that, then FM7 & WWP.

Thanx so much for your commentary!

Want to support TECHWR-L? Get shirts, bags, hats, clocks,
and more from the TECHWR-L Store. All proceeds support TECHWR-L.

Check out the new release of RoboDemo, our easy-to-use tutorial software.
Plus, buy RoboHelp Office in August and save $100 with our mail-in rebate.
Get details and download free trial versions at

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 for more resources and info.


Previous by Author: RE: Re- Do I have a right to feel POed??
Next by Author: RE: Technical Documentation solutions?
Previous by Thread: RE: Technical Documentation solutions?
Next by Thread: RE: Technical Documentation solutions?

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

Sponsored Ads