Re: need advice - writing wiki Help for web app

Subject: Re: need advice - writing wiki Help for web app
From: "Connie Giordano" <connie -at- therightwordz -dot- com>
To: Monique Semp <monique -dot- semp -at- earthlink -dot- net>, TechWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 31 Jan 2011 12:01:52 -0500

Hi Monique

The main rule to follow is Help should include whatever the user needs to
do their job using the product you're documenting. Screen shots, links to
demos, straight text, drill-down diagrams, I've seen and built a huge
variety of things for help systems over the years.

As Bill noted sequence does matter, it just doesn't happen in a mono-linear
fashion. Processes and procedures branch and merge constantly with a wide
variety of conditions possible, so some audience analysis is key to
designing the major paths that most users would follow. Procedural
information is incredibly important to newbies, to describe new
functionality, and to support users with performing infrequently used or
complex functions.

Consider using a mind-mapping tool to identify all the topics, procedures,
concepts and relationships you'll need. Then prioritize development so you
have a timeline to work towards. You may find that your landing page needs
both graphical and textual references and links to individual topic areas.
Audience analysis, and a lot of time spent on planning the design of the
help system are two of the most important things you can do to make the
development easier and more successful

Each wiki tool is different, and I'm used to building in Confluence, so
from the specific tool perspective, I won't be able to offer any assistance
there. But feel free to contact me offline if you need more feedback from
the structural design perspective. Good luck!

Connie P. Giordano
The Right Words
Communications & Information Design
(704) 957-8450 (cell)

www.therightwords.com
"It's kind of fun to do the impossible." - Walt Disney


-------Original Message-------
From: Monique Semp
To: TechWR-L
Subject: need advice - writing wiki Help for web app
Sent: 31 Jan '11 11:28

Hello, TechWR-L-ers,

Oddly for someone who?s been tech writing for so long, I have little
practice writing traditional Help documentation. But I now have an
assignment to write help for a Web app.

So I?m looking for any recommendations of quickstart books/websites,
references on the ?top 10 things to do and not do when writing Help?.

IMPORTANT ? Please try not to let this thread to morph into recommendations
for tools/approach/etc. While a more than worthy discussion, it must be
for another day for me. (At the end of this thread, I explain more;
briefly, though, I?m using TiddlyWiki to create a set of Wiki/HTML pages
that comprise the Help.)

Of course I?ve used Help, and know in the big-picture sense how it differs
from a traditional User Guide ? especially in terms of things like:

* Help generally doesn?t include screenshots.

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

* Help often seems to have less procedural info but more general background
info.

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

So what else should I keep in mind as I start?

For this project, I?m constrained to delivering the help as a TiddlyWiki
set of HTML wiki pages, and for this inaugural version, not even being able
to do context-sensitive help (where a help topic would be mapped to a given
screen). That is, there will just be a single link (I believe at the top
of the screen) that when clicked opens the TiddlyWiki HTML file in a
separate window.

I?ve already gone through the discussions with the client about whether to
go with the wiki approach, evaluated other tools, the importance of
context-sensitive and on-screen help, etc. ? but for this version they
decided to go the simple-for-development-route of just creating a single
html TiddlyWiki file that won?t require lots of back-end support (such as
would be needed for Alfresco-type solutions).

Many thanks for sharing your experience,
-Monique
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.
[LINK: http://www.doctohelp.com/] http://www.doctohelp.com

---
You are currently subscribed to TECHWR-L as [LINK:
http://mbox.server274.com/compose -dot- php?to=connie -at- therightwordz -dot- com]
connie -at- therightwordz -dot- com -dot-

To unsubscribe send a blank email to
[LINK:
http://mbox.server274.com/compose -dot- php?to=techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com]
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit [LINK:
http://lists.techwr-l.com/mailman/options/techwr-l/connie%40therightwordz.com]
http://lists.techwr-l.com/mailman/options/techwr-l/connie%40therightwordz.com


To subscribe, send a blank email to [LINK:
http://mbox.server274.com/compose -dot- php?to=techwr-l-join -at- lists -dot- techwr-l -dot- com]
techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to [LINK:
http://mbox.server274.com/compose -dot- php?to=admin -at- techwr-l -dot- com]
admin -at- techwr-l -dot- com -dot- Visit
[LINK: http://www.techwr-l.com/] http://www.techwr-l.com/ for more
resources and info.

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

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


Follow-Ups:

References:
need advice - writing wiki Help for web app: From: Monique Semp

Next by Author: Re: need advice - writing wiki Help for web app
Previous by Thread: Re: need advice - writing wiki Help for web app
Next by Thread: Re: need advice - writing wiki Help for web app


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

Sponsored Ads


Sponsored Ads