Re: Common approach to documentation

Subject: Re: Common approach to documentation
From: "Deb M." <dm -at- ptrail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 27 Mar 2003 11:38:17 -0500


From: "Simpson, Andrew" <ASimpson2 -at- averyberkel -dot- com>
> Has anybody got experience of trying to bring 2 separate authoring
> departments to a more common approach to documentation.

I have. I contracted for a US start-up (NY) that was subsequently purchased
by a company mostly based in the UK.

When I began, the start-up had no styles or formal processes. At the time of
the purchase, we (I) had a rudimentary set of styles, a fly-by-the-seat-of
your-pants-yet-documented process, and a simple single-source method (FM to
WWP, no frills/all platforms). Hard-copy docs were printed from the PDF and
manually assembled as needed.

On the UK side, they had a style guide, a formal review process, sent
manuals to a professional printer (with color separations), and even had
their CDs silk-screened. They created their online Help using RoboHelp after
the manuals were written. The products developed over there were "mature"
compared to those on this side.

On the bright side, we both used FrameMaker and the UK side had standardized
on US English.

The first and easiest task was converting my docs to use their templates.
(Praise Providence for FrameScript.) The last, hardest, and never completed
task was giving up WWP for RoboHelp.

> 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.

Early on, someone from the UK side quipped that we were "two countries
divided by a common language." Inside the joke is the truth that we are
culturally very different. Couple that with start-up culture vs. established
enterprise.

I was impatient with their process/beauracracy and may have made disparaging
comments about it. Consider that my process allowed me to make changes to
the docs right up until 12 minutes before the build. Given my development
team's process, I needed that flexibility. I didn't have the luxury of
burning 4-6 weeks out of a 2-3 month release cycle to send a manuscript to a
printer. In addition, I was puzzled by the fact that the writers on the UK
side were not willing to speak up in meetings (the way they did in the
pubs.)

On the other hand, I learned that they were horrified that I would ship
documentation without the proper review forms, signed and filed. I also
found that they were amused/shocked that I would speak up at meetings (in
that special way that New Yorkers can).

The saving grace was that we all liked each other as people and respected
each other as tech writers. As a bonus, based on our discussions, we were
able to initiate some changes in the development process that benefitted the
company.

> Any ideas?

For the team:
- Do like and respect each other. If you haven't already, plan some trips so
folks can meet each other. I know it's expensive, but it's really worth the
money. Really. In addition to all the benefits that go with having 3-D
colleagues, there's the excitement of traveling that can help soften the
fear of change.
- Put to rest any fears about whose jobs will be cut. (If you're not cutting
anybody, let everyone know that. If you are cutting folks, do it and be done
with it.)
- Take as much time as you can get. Do it in phases.

For the docs:
- Start with the end-user requirements and work backwards. Figure out what
you need, what you have and connect the dots.
- Assess your tools. Can you use FM for one product and PM for the other? If
not, which tool best meets the needs of the whole group as well as the
product line? Provide training for those who will have to make the switch.
Often, training facilitates a willingness to change.


That's it, off the top of my head. Good luck!


Cheers,
Debbie
www.ptrail.com











^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.



References:
Common approach to documentation: From: Simpson, Andrew

Previous by Author: Re: Writing help at home
Next by Author: Help needed: FM bodypage/masterpage graphic interference
Previous by Thread: RE: Common approach to documentation
Next by Thread: FW: Common approach to documentation


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


Sponsored Ads