Re: need advice - writing wiki Help for web app

[Tony Chung <tonyc -at- tonychung -dot- ca>]

Hey Monique,

I'm in the same boat where I've never been asked to write help, so I
didn't even bother to take the course on it in my certificate program.
It appeared to focus more on tools than process and wouldn't have
helped me. Pardon the pun.

In discussions with others on this list and IRL, I hear about the
books Is the Help Helpful and The User Is Always Right.

I disagree that help should not include screenshots. In this modern
age pictures tell more than text. Were I to write help content I'd
look at other help systems to see where they fail. For instance, the
search feature needs to consider term variants and scope.

There was a time while researching a function in Word's OLH, I found
all sorts of results for Access and Excel instead of Word. That
shouldn't happen.

Do share your findings. Oh Tiddly Wiki
sounds cool.

-Tony



On 2011-01-31, at 8:28 AM, Monique Semp <monique -dot- semp -at- earthlink -dot- net> wrote:

> 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 tonyc -at- tonychung -dot- ca -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/tonyc%40tonychung.ca
>
>
> 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
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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