RE: Phrasing question for software documentation

Subject: RE: Phrasing question for software documentation
From: <laura_johnson -at- agilent -dot- com>
To: <litlfrog -at- gmail -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 22 Apr 2011 15:43:34 -0600

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,

-----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.

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

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 for more resources and info.

Please move off-topic discussions to the Chat list, at:

Phrasing question for software documentation: From: Joe Weinmunson

Previous by Author: Re: Payment Delay in 1099 Employment Contract
Next by Author: RE: Flare question: Orphan xref tags in HTML that don't appear in WYSIWYG editor but do appear in build
Previous by Thread: Phrasing question for software documentation
Next by Thread: Flare question: Orphan xref tags in HTML that don't appear in WYSIWYG editor but do appear in build

What this post helpful? Share it with friends and colleagues:

Sponsored Ads