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