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: HTML as document source From:Bill Hartzer <XBJH%mimi -at- MAGIC -dot- ITG -dot- TI -dot- COM> Date:Fri, 19 Jul 1996 09:43:01 -0500
Hi Angela,
My first impression, after reading your question regarding developers
changing things online, is that you're allowing the developers to decide
how you do your job. I've run into situations like this myself, and it
was a nightmare whenever the developers did changes to documentation.
When a developer is given the 'source file' to make changes, technical
writers cannot control the documentation; typos, bad grammar, and
stylistic issues come into play when those who are not in our profession
take over and try to do our jobs. There are, of course, many developers
who do this with good intentions. However, there is no way you, as a
technical writer, can win when someone else steps in. Here are several
reasons why I think this way:
* We don't step in and write code and make code changes for developers so
they shouldn't try to fix our documentation.
* There is no way to control (find out) what changes are incorporated
into the documentation.
* Some changes just don't belong in the manuals. Sometimes it would
actually hurt the users (or confuse them) if certain things got placed in
the manuals.
* It's a tech writer's job to control the usability of documents.
* If you give an SME the chance to make minor changes, they might even
step over the line and make stylistic changes as well.
* I've never seen documentation that was written by an SME that wasn't
riddled with typos, spelling errors, and grammatical errors (just
kidding).
* Keying in changes to documentation is only a minor task in the scheme
of things. It really only takes a small percentage of our time to key in
changes (if you're a good typist). Developers should make changes to
hardcopy docs with a red pen.
* Changes need to be tracked; the writer should have some way of
determining which SME is responsible for what change.
* If developers are so adamant about making changes online, them give
them a copy of the doc electronically so they can insert 'notes' into the
doc so you can make the changes.
* If developers maintainted the documentation, technical writers wouldn't
have a job; most of my work exists because new releases of software come
out and changes must be made to the documentation in order to reflect the
changes in the product.
* Source documents should almost always be maintained in programs like
Framemaker and Interleaf (just to name two as examples) because the
documentation will always look better if it's done in a DTP package like
this. One can always 'spin off' a copy of it in HTML, Adobe Acrobat,
Electronic Books, etc.
* Technical writers should always have control of the documentation and
should always have the final say in what goes into the manual. I don't
tell an SME how to write code; they shouldn't tell me how to document.
* If you pass on all of your extra work to SMEs, us contract technical
writers would never have an opportunity to step and help you out when
you're in a time crunch.
There are MORE reasons why SMEs should never have access to the source
documentation files, but that's all I have time for right now.
--
Regards,
Bill Hartzer Bill Hartzer
Contract Tech Writer President
Texas Instruments, Inc. Highfield Marketing Group, Inc.
Dallas, TX USA Irving, TX USA
xbjh -at- msg -dot- ti -dot- com Highfield -at- aol -dot- com
(214) 575 - 2041 (800) 664 - 3251 toll free
(214) 798 - 2976 voice pager (214) 506 - 0111 fax
========================================================================"Highfield Marketing Group, Inc. is the proud maker of the CD-ROM
TalentBank(tm), an electronically searchable resume database full of
quality professionals in the computer, high-tech, and technical writing
industries. Never a fee for applicants. Employers and recruiters
can search thousands of resumes electronically on their desktops while
applicants can reach thousands of employers with their resume."
========================================================================
TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send administrative commands
ALL other questions or problems concerning the list
should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-
