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