Re: How is your pubs dept set up?

[Mary Deaton <Marymd -at- HALCYON -dot- COM>]

>Kendall Robinson writes:

>"...how is the pubs department set up in your company?  Do you have
>separate resources doing the on-line help?  Do you feel it's possible, or
>a good idea, for
>writers to write manuals and develop complex hyper help systems
>at the same time?"

>Hi Kendall,

>Your email made me grin a little.. I've worked for a software company in
>growth mode for the last five years... Since January 1990, the company has
>gone from about 50 employees to 500 worldwide. When I started five years
>ago, there WERE no tech writers. Back then, I wasn't even allowed to ask
>the programmers questions about the product! Now, we have a department of
>about 15 people, five of whom have joined within the last month, another
>five within the last six months!

>However, enough radio chaos and reminiscing...

>IMO, there isn't really a dichotomy between on-line help writers vs.
>technical writers who develop printed manuals. The writers at our company
>do both. (Plus training materials!) What's more important than anything
>else is the ability to quickly synthesize and then regurgitate information
>in whatever format is required. (Hi-tech bulimia?)

>Here's more advice than you probably want--but it sounds like your company
>is currently about where ours was two years ago. Here are some things to
>do now (or conversely, things not to do) while you still have a beast
>that's relatively tameable:

>1) If your company hasn't reorganized into multi-functional teams yet...
>push for this, because it really does promote concurrent engineering! Our
>company went through a reorg earlier this year. Documentation initially
>opposed it because it meant that our group was going to be split up and
>scattered throughout the R&D building. However, it is working out pretty
>well. The cross-fertilization between programmers, application specialists
>who work a lot at customer sites, and technical writers has been very,
>very helpful.

>Just to give you an isolated example--on my team, after we put the
>developers and application specialists through one two-hour training
>session on writing on-line help... they helped us improve the software
>tool we use to create our on-line help! Before the reorg, (1) we would
>never have thought we could improve that tool and (2) even if we had, we
>would never have had access to the programming resources to do it!

>Don't be afraid to allow "non-writers" to write. With the proper guidance,
>they can do reasonably well. In the years to come, you're going to find
>that your job is not only to write, but to make it as easy as possible for
>subject matter experts to write your rough-draft documentation. DO NOT
>INTERPRET THIS AS A THREAT TO YOUR JOB SECURITY! It is much more of a
>threat if your department is perceived as a bottleneck within the
>organization... Especially if your department is overworked, this is the
>direction to go.

>2) Buy the very best production tools you can afford! We are about to go
>to Framemaker, after having limped along with Ventura Publisher for
>several years. Be careful before you select your on-line help system! If
>it's complicated to work with, not only are you going to go berserk, but
>so will any "non-writers" who have to work with it!

>I'm currently working on the online help and release bulletin
>simultaneously (thanks to Windows and Reflection X, a nifty workstation
>emulator package for PCs). When I'm through, my final products are going
>to be much better than anything I've ever been able to write at this
>company.

>3) Get your electronic document files as organized as possible NOW, before
>you have a bazillion of them! (We are currently having to do a lot of
>housekeeping because we're starting to send docs out on electronic media.)

>4) Develop a style guide if you don't already have one. Five years into
>the fray, we're just developing one now...

>5) Investigate information mapping. If you can design a process in which
>information is transferred as seamlessly as possible between requirements
>definitions and technical specifications to on-line help, printed manuals,
>and training materials, you'll save yourself lots of time and errors in
>the long run.

>6) Take a tip from the software developers and establish mini-deadlines
>rather than having to finish everything in time for the BIG HORRIBLE
>LURKING DEADLINE! Take the attitude that, OK, September 30, we'll print a
>draft of whatever's in the draft on that date and not worry about what's
>going to be put in next week--that way, people can be reviewing it as
>they're working on related projects. (Also, this gives you something
>tangible to hand the company president who's convinced that you're not
>earning your keep...) Then, between now and, oh, October 31, you make
>corrections, and at the end of the month you print out another draft.

>We used to try to have everything done by one specific deadline. This was
>a colossal mistake! Aside from being massively stressful, our
>documentation was full of errors because there was no review time built
>into the schedule...

>7) Don't work more than 50 hours a week! I used to kill myself with long
>hours. This year, I cut back to about 45 hours/week, and I'm still as
>productive, but I also have time and energy for other activities besides
>work!

>Good luck!

>Rgds, Madeline Bechtold (mmb -at- qad -dot- com or MMB1 -at- aol -dot- com)


Don't forget, there are products out there especailly designed for
 single-sourcing Help
and print so one writer than write both at the same time and then "compile" the

information into the two media they belong in. Doc-to-Help is probably the most
 popular
one. It is Word based because Word produces an RTF file the Help compiler has no
 trouble
reading (assumning you mean Windows Help). There are also products that will
 compile for
multiple platforms. I won't every again waste a client's money having someone
 program
Help authoring tools in house.

The trick here is not in whether one writer can manage to learn both, but in
 designing a
system that results in the right information in the right media. Single-sourcing
 is
tricky. You cannot simply reproduce what is one paper online. But Doc-to-Help
 and other
tools let you designate where information ends up and because one writer is
 doing it
all, you get much greater consistency of language, tone, and style. This can cut
 an
editor's time tremendously.

Anyone having to do Windows Help should make choosing an authoring tool one of
 their top
priorities: there are some excellent ones out there that will save you a TON of
 time.

Mary Deaton
KNOWware: Information You Can Use