RE: suggestions on how to "hide" UI-based topics in online Help TOC?

["Christine Kent" <c -dot- bkent -at- bigpond -dot- net -dot- au>]

If I have understood, this all sounds pretty standard to me.

Both types of documentation are required.

We used to use terms like User Guide for process based documentation, and
Help for function based documentation.  Software development projects often
do both kinds of documentation, as they serve different needs.  Some people
need to work out how to do the job so they want the process based
documentation, and some people just need to work out what to do with a
particularly nasty field, so they need the function based documentation.

You just find two different heading names for the two types of
documentation, and let the users work out which one they need.  Put all the
old stuff under "Field and screen help" and put all your new stuff under
"Processes and procedures"  or somesuch...

ck



> -----Original Message-----
> From: techwr-l-bounces+c -dot- bkent=bigpond -dot- net -dot- au -at- lists -dot- techwr-l -dot- com
> [mailto:techwr-l-bounces+c -dot- bkent=bigpond -dot- net -dot- au -at- lists -dot- techwr-l -dot- com] On
> Behalf Of Ned Bedinger
> Sent: Tuesday, 25 March 2008 9:42 AM
> To: Donna Barbieri
> Cc: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: suggestions on how to "hide" UI-based topics in online
> Help TOC?
> 
> Donna Barbieri wrote:
> >  the Help system is 100% UI specific. Topics such as
> > "using XYZ" really include information about what is
> > on a particular screen.
> 
> The design you've inherited is nothing more than a systematic, linear,
> descriptive pass through each feature of each screen in the
> application.
> 
> > I have been tasked with creating "usable" Help for
> > first time users AND with keeping the existing Help
> > for a release in the next two weeks.
> 
> Your task is to create task-oriented help topics, and also to spin (my
> word) the existing feature-based topics as something useful to your
> users.
> 
> > Since, apparently, this HAS to be there I'd like to
> > minimize it's impact on users.
> 
> The task-based prescription is normally good, so you've got the plan
> for
> how you'll minimize the impact of the original deficient design.
> 
> I am thinking of
> > introducing the task-based topics as one normally
> > would and then renaming all the existing topics and
> > including them in a logical hierarchy.
> 
> If I guessed right, they already have the logic (each topic of each
> page).
> 
> <snip>
> 
>  > what should these "topics" be called I
> > really want to steer away from "using XYZ Page" and
> > was thinking "XYZ Options" "XYZ Page" "About XYZ"? Any
> > suggestions?
> 
> You're going to have to switch hats and think about how to spin them as
> something that your users need or could use. IOW, sell them to the
> users. If you can discuss this with representatives of the users,
> great.
>   Otherwise, I think you'd want to do everything in your power to avoid
> casting them to the customers as hokey, ineffectual topics that you've
> bundled, for reasons of nepotism, with the real help.
> 
> So step back and look at the problem objectively. At the very least,
> the
> existing topics form a reference to everything in the UI. Right? Could
> they pass as a tutorial?
> 
> Ned Bedinger
> doc -at- edwordsmith -dot- com
> #include standard disclaimers
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> 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 c -dot- bkent -at- bigpond -dot- net -dot- au -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/c.bkent%40bigpond.net.au
> 
> 
> 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.
> 
> No virus found in this incoming message.
> Checked by AVG.
> Version: 7.5.519 / Virus Database: 269.22.0/1341 - Release Date:
> 24/03/2008 3:03 PM
> 

No virus found in this outgoing message.
Checked by AVG. 
Version: 7.5.519 / Virus Database: 269.22.0/1341 - Release Date: 24/03/2008
3:03 PM
 

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

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- 

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.