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.
> From: Keith Hood [mailto:klhra -at- yahoo -dot- com]
> Sent: Saturday, July 28, 2007 11:10 PM
> To: Lauren
> Cc: 'TECHWR-L'
> Subject: RE: Examples/one other thing
>
>
> --- Lauren <lt34 -at- csus -dot- edu> wrote:
>
> > I don't
> > see why the user needs to know about the design
> > details.
>
> Sorry, I really meant the references would give
> information at the user level. I wasn't thinking about
> trying to explain the try loops and the branching
> structures in the Java code to the users. I meant the
> reference should give user-level explanations of
> things like how the program reacts to changes in
> aircraft status, and the actions it takes to comply
> with regulations.
Why do you need a separate document for this? If there is information that
a user needs to know for operating the system, like changes in the aircraft
changes the program, then it should be addressed in the operations manual.
Compliance aspects of using a system can be and, I think, should be
addressed in the operations document as well. My reasoning is that we can
expect a user to pick up bits and pieces of important information from
different documents when one document can provide that information.
Documentation that I have produced to support using systems that maintained
HIPAA requirements and requirements for using government did address the
applicable rules within the document. For example, I addressed that social
security numbers could no longer be used as identifiers and data uploaded to
government systems required certain formatting. I also provided references
and web addresses to applicable documents so that user could get the
compliance rules themselves.
I would not risk producing a separate document that claims to provide the
compliance rules that apply to the user when the rules are documented
elsewhere because there is a risk that required rules will be misinterpreted
by the users based on what I write. For me, I prefer to state in the
document that the purpose of this task <or whatever> is to comply with x
rule from x. I will also provide a reference to the official document that
requires the rule, but I won't interpret or discuss how this rule applies to
the system. I only discuss that the system or particular task is attempting
to comply with the rule.
I know this is a lengthy response, but compliance regulations are a little
serious.
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
