RE: Your opinion, please!

[Rose -dot- Wilcox -at- pinnaclewest -dot- com]

Brian, this sounds a lot like the power trading industry, which I work in.

"About half of our clients operate in a heavily regulated environment. The 
regulatory body demands that our clients communicate their day-to-day 
transactions to the regulatory body with XML. We've customized our software 
for those clients, and continue to do so (for a fee) as the regulations 
change"

In terms of changing regulations, don't the regulatory bodies in your industry have websites that you can refer customers to?  For the most part, I hate to restate the changing regulations for my clients, except as absolutely necessary, and even-then, at a high level.  In fact, it would seem with the XML you would be driven to use the websites or documents of your regulatory bodies to create the code, so you would already have them at hand?

"First, I want to recommend a handful of mini-tutorials (delivered online 
somehow) that illustrate the concepts. Using diagrams and a conversational 
tone, I want these docs to teach the concepts that clients need to 
understand before they can start to solve their own problems. These concepts 
won't change much over time, so I'm pretty sure it will be worth the effort 
to develop the content.

But the rest of the information -- the tactical, click-by-click stuff that 
changes every few weeks as regulations change -- seems to be a maintenance 
nightmare in the making.

So I'd like to deliver it in a kind of knowledge base. Here's what I mean by 
knowledge base: Informal "articles", planned by me but written by subject 
matter experts around the company, added to our support Web page."

In terms of your plan, basic concept docs supplemented with a KB, the only difficulty I see with that is that in my experience as a reader, there is sometimes a gap between basic concepts and being able to use/understand the KB.  In other words, as a consumer, I read and understand the basic concepts, but still get bogged down as I navigate through the KB because of unfamiliarity with intermediate concepts or vocabulary.  You might want to think of some migation for that possibility especially as SMEs will be writing the KB articles and often will not "hand hold" readers as far as terminology or basic concepts go.

Also you have not clearly defined your audience, the clients.  Or if you have, you didn't share that little piece with us.

What jobs do they do?  Why are they using the software?  Do they need to understand the whole software or just a piece of the software?  Do they have to customize the XML themselves or can they use it as is?  What is their industry background?  Are they clerical, management, technical?  

You might need to consider going back to the drawing board before you go further.  

I see this a lot on Techwr-l.... forgetting that audience analysis must come first and drive all our other decisions regarding what and how we deliver information.  Like how and when to use acronyms... <ducks>....


Rose A. Wilcox
CHQ, 17th Floor
Tranz1 QA/Documentation
602-250-2435
Rose -dot- Wilcox -at- PinnacleWest -dot- com

Maggie Secara: "It's really sad when someone can't even get a cliche right." 

Arthur Hlavaty: "They say that when you get older, you lose your allusions."
- From the Copyedit-L





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

Robohelp X3, from eHelp, lets you quickly and easily create
professional Help systems for all your Windows and Web-based
applications, including Net.

Buy RoboHelp Office X4 by June 13th and receive
$100 mail-in rebate, Plus FREE RoboHelp Plus Pack.

Order RoboHelp today: http://www.ehelp.com/techwr-l

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