TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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!
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-
