Re: need advice - writing wiki Help for web app

[Di <dicorrie -at- gmail -dot- com>]

i like to read on what people have to say about designing help files so
here are a few thoughts from me; hoping to read a few more of yours....

> > * Help generally doesn’t include screenshots.
>
> ...unless necessary.
>

i tend to translate this one thus:
. dont use screen shots to illustrate procedures (why would you when you
have got the app alongside)
. in other contexts a screenshot or part of a screenshot, perhaps with
annotation or two, will illustrate the general principle of using raphics in
documents - look nice and be a 'picture tells a thousand words'.

> * Help needs to 7explain *how* to get to a particular function – that is,
where on the screen to click to get to the function’s dialog box (yes, other
docs need this, but it seems to be particularly lacking in Help system).

> Actually, it needs to explain how to perform a task. What you are
> referring to is UI reference, which is a very small part of Help.
>

I make sure the path to where a task/procedure starts is included in the
same topic as the task/procedure. not much different to a user guide in this
respect.

>
> > * Help often seems to have less procedural info but more general
> background info.
>
> That's because Help is often written poorly. ;-) Help should be just
> that - help! Background isn't helpful if a person is sitting there
> silently screaming "I just want to [do X] and get on with my job!"
>

Agreed, the primary purpose of application help is as for a user guide and
should be oriented towards things a user needs/wants to do.

I find it easy to stuff conceptual / background information into a help file
than a user guide and if the additional cost is insignificant, I'm
tempated. with all the relevant concetpual/background in then I have got
what I fondly call 'a single store of help information' . The core
purpose, making it easier for users to user the app with task oriented info,
does not change.

>
> > * Help is certainly geared to online viewing, not a start-to-finish PDF
> read, and so sequence is not really relevant; nor things like print-book
> frontmatter, page numbers, chapters, etc.
>
> Sequence is definitely relevant, you just approach it in a modular
> (topic-oriented) fashion. Sequence isn't a single linear path in this
> case, but a series of related paths. And yes, you can forget about
> book conventions.
>

Totally totally totall agree about sequence. I put a lot of thought into
that. Well designed, people will tell you your help is easy to navigate, -
if they are expert users they will even enjoy to look for what is there. Bad
sequence design will turn users right off, they will get confused, feel like
they are getting 'lost in space'.


>
> > So what else should I keep in mind as I start?
>
> Avoid fluff. Discuss only one topic at a time. Make the content
> relevant to using the product purposefully.
>
yes. alongside with this think about how the cross references from a topic
will work and the topic naming conventions so that related content is clear.


>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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. 
http://www.doctohelp.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. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat