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.
> I need the benefit of your collective experiences... as tech
> writers, we frequently are documenting products that are still
> under development, so that the documents can ship with the product,
> no?
>
> OK, so what have you done when faced with a feature that is at
> best, "buggy". Sometimes it works, sometimes it doesn't. If you
> write a procedure according to the way it's supposed to work (i.e.,
> design intention), then your book is wrong at least part of the
> time.
I don't think a blanket answer will work here. Depending on the bug,
how it is invoked, under what conditions, I've been in situations
where it WASN'T going to be fixed until the next release, so to say
write it as it should work hoping it will get fixed by release can
get you in trouble.
First, you need to contact someone in your development community to
find out what their plans are for the bug. Are they going to fix it,
leave it, or rewrite a complete section of the
application...sometimes, that's the only way.
Assuming they are going to fix it with no change to anything else,
then yes, write as it should be, then verify it against the document
while in final testing.
If you find that it isn't going to be fixed, perhaps you can write
something harmless in the documentation that will hide the bug. Let's
say that a field blows up when you enter data in a certain way. An
example is that if they enter a date prior to today, boom. At that
point in the document, place a note that says something to the efect
"At this field, you must enter a date that is today's date or later."
You don't have to tell them what will happen if they don't. If they
do, they'll find out on their own.
If the interface is going to be changed to accomodate the bug becuase
it is a symptom of a much larger issue, then you nedd to hold off
until the very last minute until you have some direction from
development.
In any case, just to say "write it asa it should be...the fix will
happen" is not real-life.
=====
John Posada, Senior Technical Writer
"I'm not flying...I'm falling with style"
---Buzz Lightyear
-----------------------------------------------
Current gig ending 5/15
Resume: http://www.tdandw.com/Resume_Posada_022202.doc mailto:john -at- tdandw -dot- com, 732-259-2874
__________________________________________________
Do You Yahoo!?
Yahoo! Health - your guide to health and wellness http://health.yahoo.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com
Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr
---
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.
