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.
(Whoops! I changed the subject line back to "dispensing...")
Au contraire, David, mon ami. Putting on the appropriate
finishing touches is manageable, and I don't think I implied that
it was a problem. The issue, and I seem to be having a problem
getting it out onto the table, is the Procrustean treatment of
the doc cycle. Remember Procrustes? He had the utterly mad
method of applying a single solution to any problem. See http://www.pantheon.org/articles/p/procrustes.html for brief
refresher. BTW, I thought Polypemon (sic) was the Cyclops.
Anyway, The key was to recognize that we were servicing the goal
of expediency. not the high values of documentation. I would
contrast this with the developer's work plan, which seems to me
to have clearer goals. But I believe that very few of us got
into tech writing as an expression of our admiration for
utilitarianism over precision/thoroughness. We'll always feel
trapped by any requirements that short-circuit our refined
expectations. Very few of us develop those fur-lined deadline
skills just so we can take on projects in crucibles where agility
and expedience prevail over traditional drivers like 100% topic
coverage and reviewed documentation. Watermarks and TBD notes
are easy enough for us to do, but shortening delivery time by
dropping reviews from the schedule??--we've spent nights and
days, weeks and years training our neurons in how best to get
reviews. I study this far more than grammar or illustration,
layout or design. I would rather try and compress the timeline.
Drop what you're doing and send it? This is a recipe for instant
cognitive dissonance! The good news is that we're adaptable, the
envelope is expandable, and testing continues as tech writing
grows into new extremes of business models. The bad news is that
expediency, as conceived by un-empathic other interests, could be
a test to destruction, if it become more prominent in
documentation requirements.
--Ned "am I editorializing yet?"
--- Original Message -----
From: "David Neeley" <dbneeley -at- oddpost -dot- com>
To: "Ned Bedinger" <doc -at- edwordsmith -dot- com>; "TECHWR-L"
<techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Tuesday, June 01, 2004 7:01 PM
Subject: Re: Marketing view of documentation was Re: dispensing
with documentation reviews
> Ned,
>
> It shouldn't be against any of your professional pride or
discipline to do the same thing the developers do with a new
prototype...label the docs as "preliminary" or "alpha" or
whatever to indicate it is not the finished product.
>
> If you're still writing the finished doc, you should have a
good handle on the design templates. Thus, whatever you have
should *look* fairly good, right?
>
> You may want to use a "watermark" on the pages to indicate the
document is "preliminary" and a suitable disclaimer up
front...and, in fact, you may well include contact info for
collecting errata. That, properly handled, may give the users of
this "test release" a feeling of ownership--and you may also get
useful feedback in the process.
>
> Where you do not yet have particular features detailed, I
suggest you indicate that you know the material is missing, too.
If yours is a somewhat typical development case, there is
"feature creep" up to the last minute--then folks are screaming
at the tech pubs department that *they* are delaying shipment of
the finished product. Surely there are ways in which you can
indicate that a feature is not yet stabilized enough for finished
documentation?
>
> David
>
> -----Original Message from Ned Bedinger
<doc -at- edwordsmith -dot- com>-----
>
> "Marketing" was the name of the internal group that wanted
> incomplete documentation releases with all of the bows and
> ribbons, like a finished product. Ann Pai may find this
> interesting because that Marketing department was an example of
a
> group that had the power to drive the documentation
requirements,
> and used it in a way that ran counter to my professional
values.
> To them, the documentation, whether complete or not, would
> fulfill their commitment to providing documentation along with
a
> test release of the software. If I had not understood the
> special requirement for delivery of a good looking but
incomplete
> doc set PDQ, it would have seemed that Marketing had arrogated
a
> large portion of the tech writers' professional role,
humiliating
> us and our best efforts by shipping out a "pig with lipstick."
SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content
Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo
>From a single set of Word documents, create online Help and printed
documentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more. http://www.doctohelp.com
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.
