Re: need advice - writing wiki Help for web app

Subject: Re: need advice - writing wiki Help for web app
From: Bill Swallow <techcommdood -at- gmail -dot- com>
To: Monique Semp <monique -dot- semp -at- earthlink -dot- net>
Date: Mon, 31 Jan 2011 11:44:42 -0500

> * Help generally doesn’t include screenshots.

...unless necessary.

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

> * 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!"

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

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

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

TiddlyWiki? How are you architecting the navigation to topics? Also,
how are you guarding against (potentially unwanted) changes?

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

I use TiddlyWiki daily for personal notes and such, but I'd be
interested in hearing how using it as a Help file works out. I'm
skeptical, but I'll keep my fingers crossed for you!

Bill Swallow

Twitter: @techcommdood

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.

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

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 for more resources and info.

Please move off-topic discussions to the Chat list, at:


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

Previous by Author: Re: throughput
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