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.
Subject:RE: Common approach to documentation From:"TEA Lanham, Kevin" <Klanham -at- aus -dot- telusa -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 27 Mar 2003 10:18:13 -0600
Andrew,
Every situation is different, but here is ours.
We had 7 manuals groups worldwide all doing different things with different
tools. They all belong to separate companies. Then our customers complained
that our parent organization looks and acts like a bunch of different
companies. Soon after we had an unfunded mandate to act like and have all
our products look like they came from one company.
So we surveyed the tools used. We got back Word, Frame, Webworks, RoboHelp,
Epic, SGML tools, HTML editors, etc.
Because we have been asked to have the look the same for all groups we set
up a committee to work on the common layout decisions. It turns out that
cultural differences may cause us to have layout differences by regions of
the world.
We chose to move everyone to XML so that we can more easily develop style
sheets for everyone that take the data and format it the same way without
having to convince 75 writers around the world to all use the same
conventions (hoping that they all really do it).
We are gradually moving everyone to XML and teaching them how to write using
and XML editor and how to tag content with a DTD.
This is a long process with 7 groups speaking different languages. Everyone
was protecting their tool choice so we had to evaluate all the tools and
show the details about why the winner was proposed for all. Frankly, even if
we have some degree of resistance on the authoring software, if each group
outputs valid XML, then it will all be OK.
We've got one group developing the XSL style sheets for all but they are
taking their direction from the layout committee. The people that had no
desire to get technical with the XML stuff migrated toward this effort. The
layouts are for print, Help files, and web content.
Those inclined to learn more about XML and DTDs formed a vocal committee for
the DTD development. If you've got no experience in writing DTDs, it may be
easier just to start by adopting DocBook than creating your own. It may be
cheaper this way too unless you've got some developers on staff.
This effort takes alot of teleconferences, videoconferences, and
face-to-face meetings. It takes a near constant barrage of emails. Some
groups are more involved sometimes than other times based on their
schedules. The leader of the effort may feel more like a politician than a
writer.
It takes *at least* 18 months to make a transition like this. You may or may
not decide that this path is one you want to take. For our company it makes
sense. Good luck.
Kevin
-----Original Message-----
From: Simpson, Andrew [mailto:ASimpson2 -at- averyberkel -dot- com]
Sent: Thursday, March 27, 2003 4:14 AM
To: TECHWR-L
Subject: Common approach to documentation
Has anybody got experience of trying to bring 2 separate authoring
departments to a more common approach to documentation.
The company I work for recently merged with a US company. We now have 2
authoring departments; a small team in the US producing books for North
America & Canada, and a larger team in the UK doing the European / rest of
world books & world-wide translations.
An immediate problem has been the amount of documentation re-work involved
when taking the US products here in the UK and vice versa.
The 2 departments produce very different documents (exaggerated by the fact
that one dept uses Framemaker, whilst the other uses Pagemaker).
I have tried to get a discussion going to look at what compromises can be
made and how we can move forward, but have met with stubborn resistance to
any change.
Any ideas?
Andy Simpson
Avery Berkel, Team Leader Technical Author mailto:asimpson2 -at- averyberkel -dot- com <mailto:asimpson2 -at- averyberkel -dot- com>
Tel: +44 (0) 121 568 1674
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Order RoboHelp X3 and receive a $100 mail-in rebate, plus FREE
RoboScreenCapture, WebHelp Merge Module and iMarkupSoftware, for a total
giveaway value of $473! Order here: http://www.ehelp.com/techwr-l
Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday 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.
