Fw: New Writer Seeks Advice

Subject: Fw: New Writer Seeks Advice
From: Suzy -dot- Davis -at- doi -dot- vic -dot- gov -dot- au
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 5 Jan 2005 13:51:14 +1100

Hi Casey

First thing - who are you writing for and what are you writing? User
guides or system documentation? For what level of user? Software users can
be beginners or advanced, system administrators need to know how to manage
the administration of the software, a general user does not.

System architecture documentation and Functional specifications are usually
written before the system is developed, and are used to drive the
development. But these documents are often not updated when requirements
change during development. These documents can tell you what was
originally intended and can be useful from that point of view to have some
context to questions like, Why did they need to do that?, and it may also
tell you about functionality that you didn't find when you investigate the

It is extremely rare that you would only write one manual for a software
application. User documentation is often limited to user access rights.
With inhouse applications in particular, we don't want people without
access to particular areas of an application to know what they could do if
they had access. Inhouse documentation is usually written on a needs to
know basis for security reasons. So even if someone happened across an
administrator's login and password they wouldn't know how to bring the
system down or do other damage to the extremely valuable corporate
information stored on the system.

If it is a user guide that I am writing, it can depend on whether this will
be a completely new experience for the user to incorporate, or whether it
is replacing an old outdated system. In the first user procedures will
change dramatically and the user guides will a part of the change
management process.

I start with talking to a SME (subject matter expert) about what the users
need to know, and what they will need the most help with, what will be the
most useful to them. The SME I seek out understands and defined the
business rules requirements for the project team. I then check out the
software and document it as a user would do their job.

But I don't write documentation for mass market software, I write
documentation for inhouse custom built software. But even if you are
documenting software for the mass market it gives the reader context if you
can incorporate at least general user procedures. What are they doing
outside of the software when they need to do something with the software.

Hope this helps get you started.
Any personal or sensitive information contained in this email and
attachments must be handled in accordance with the Victorian Information
Privacy Act 2000, the Health Records Act 2001 or the Privacy Act 1988
(Commonwealth), as applicable.

This email, including all attachments, is confidential. If you are not the
intended recipient, you must not disclose, distribute, copy or use the
information contained in this email or attachments. Any confidentiality or
privilege is not waived or lost because this email has been sent to you in
error. If you have received it in error, please let us know by reply
email, delete it from your system and destroy any copies.



RoboHelp X5 is a giant leap forward in Help authoring technology, featuring all new Word 2003 support, Content Management, Multi-Author support, PDF and XML support and much more! View an online demo: http://www.macromedia.com/go/techwrldemo

You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

Previous by Author: Re: Striving To Increase The Page Count Was: Estimation of the number of pages...
Next by Author: Re: System for cleaning up legacy Word docs?
Previous by Thread: Re: New Writer Seeks Advice
Next by Thread: Re: New Writer Seeks Advice

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

Sponsored Ads