need advice - writing wiki Help for web app

Subject: need advice - writing wiki Help for web app
From: "Monique Semp" <monique -dot- semp -at- earthlink -dot- net>
To: "TechWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 31 Jan 2011 08:28:25 -0800

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

Previous by Author: TIP - hotfix for Word 2007 spell check for words w/non-breaking hyphens
Next by Author: Re: For V/s Of
Previous by Thread: Re: Convert 1200 page PDF with Tables to Word
Next by Thread: Re: need advice - writing wiki Help for web app


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


Sponsored Ads