RE: Phrasing question for software documentation

[<laura_johnson -at- agilent -dot- com>]

With any luck you've already solved this, but hey, it's Friday afternoon. :-)

Not surprisingly I can't quite tell what it is that you're trying to explain. As a writer of software documentation, I've had many problems of this sort myself; I usually start by giving myself permission to be as verbose, colloquial, and specific as seems to be necessary to get an accurate, comprehensible explanation down on paper. Then I try to tighten it up. 

So in this case, you might start with an annoyingly long paragraph (or maybe a bullet list) of this nature:

You can now add a bill code, or recurring billing amount, to customer accounts. You can do this only for customers who have xyzzy bill code already on their account. You can also obviously remove the bill code, but only once it's been added, and only for customers who.....

(Just by doing this exercise, I've noticed that you may not want to lump "add or remove" together the way you've done it. I have a suspicion that's messing with your logic.)

Hope it helps,
-Laura

-----Original Message-----
From: Joe Weinmunson [mailto:litlfrog -at- gmail -dot- com] 
Sent: Tuesday, April 19, 2011 7:34 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Phrasing question for software documentation

I'm trying to document a new global change that our billing software
can make. Our userbase is generally not very tech-savvy. The change
adds or removes a "bill code" (that is, a recurring billing amount)
for a large number of customers at once. The option I'm stuck on is
explaining a conditional setting. The user can choose to add or remove
the bill code ONLY from customers who already have a certain bill code
on their account. Every time I try to write something that makes
sense, MY eyes glaze over. Anyone have advice on this? Thanks.

-- 
Joe Weinmunson

Have nothing in your house that you do not know to be useful, or
believe to be beautiful.
--William Morris

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://www.doctohelp.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat