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.
> 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.
PDF can be used for slideshows just like PowerPoint. I
think that was what Sean was getting at (I think). You
can author in any application, use a template for
on-screen viewing (IOW, not portrait view), and then
PDF the document and use Acrobat/Reader to present it
as a slideshow.
> 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.
Why not look into a reorg of the database and clean it
up rather than look for a finer seive?
> 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.
What do the writers think? You can't expect to come
in, make a blind assessment, initiate change, and
leave without their buy-in, AND expect everything to
unfold smoothly.
> 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.
But is that how your intended audience sees it? How
are the docs used? Who uses them? When do they use
them, and how? I honestly don't think you're sizing
this situation up enough to start thinking about
implementation of ANYTHING yet. (This is all intended
as constructive feedback, BTW. Nothing personal.)
> 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!
You need to talk to the team (the WHOLE team). In all
honesty, I see your 6 months being best spent in
meeting rooms, if this is indeed a corporate-wide
implementation. I see you as being the person to get
them thinking about what they need and what they can
do to fill that need. UPS is NOT a small company. Any
change of the magnitude you're talking about will
probably take a couple of years to set up, launch, and
monitor before anyone can feel remotely confident that
it will "work as designed".
> 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.
So what are their thoughts on the migration?
> 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, exactly.
You can't change directions in the authoring state and
expect the rest to fall into place. You are looking at
the issue backwards. If there are copies of documents
all over the place, that needs to be your FIRST
concern. You need to round them up, serve them from a
central location, and educate the company on how to
access these files. They need to understand that they
should not be saving files to floppies and storing
them in empty desks, making photocopies of
photocopies, e-mailing each other files all the time,
and the like. You could spend your 6 months tackling
this alone.
> 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.
And you want to do this in six months? Do you realize
the depths to which this change needs to permeate?
You're talking a full-blown code inspection for
consistency in comments, across all authoring
platforms and languages, and then deciding on
commonalities to use in those environments, creating
your DTDs and XLS cornerstones, then trying it out on
a small sampling indicative of the whole. THEN, if you
succeed in capturing the comments and refreshing the
database (yes, a database will be needed for this
undertaking), you then need to work out your
automation in the other direction - inserting and
updating the info in the documentation. Of course, all
technical issues aside, this is all resting on your
developer's mastery of the written word and collective
expertise in the field of technical writing. (Sarcasm
intended.)
> 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.
How? As I roughly stated above, you have a million and
one possible situations to account for, else you need
to spend some considerable time standardizing on the
code side BEFORE you can even think about data
extraction. My guess is that it will take you at least
6 months to get total buy-in on this, as you're
talking major overhead in all developing efforts.
Project managers and developers are not going to be
happy, as my experience shows that more developers
than not loathe going back into their code after it's
been written and approved to completely re-work the
comment markup (and possible code-side architecture).
> 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.
I really think you need to step back and look at the
big picture. You need to frame everything in. You are
not going to get corporate-wide buy-in for this, and
if you're just resting on executive-level buy-in, then
you're going to have to prepare yourself and the
executive team for a huge firefight followed by
delays, backstabbing, and failure.
You're not just talking about reworking docs here,
you're talking about re-engineering the way the entire
development and support groups at UPS do their job,
and possibly making most people revisit all the work
they've done for - at minimum - investigation, but
most-likely, rework. It can get very sloppy very
quickly if you do not map all this out for them.
Quite frankly, if I am not overestimating what you're
looking to do, this effort could take up to five years
to implement. I suggest you either start small (the
loose doc cleanup/roundup) or explain the magnitude of
this endeavor to your planning group for
consideration. This is something you should not fly
blind into; it'd be a big CLM (career limiting
maneauver).
Just my thoughts. (Not like they'd mean anything, as
the largest doc initiative I've ever managed was a
global CSR callflow system for a major healthcare
firm.)
;)
Goober
Oh, and is this international or just a USA-local
thing? Remember, most countries will need localized content.
__________________________________________________
Do You Yahoo!?
Yahoo! Finance - Get real-time stock quotes http://finance.yahoo.com
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 http://www.ehelp.com/techwr-l
---
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.
