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:Marguerite Krupp <mkrupp128 -at- yahoo -dot- com> To:Monique Semp <monique -dot- semp -at- earthlink -dot- net>, Tony Chung <tonyc -at- tonychung -dot- ca> Date:Mon, 31 Jan 2011 12:39:45 -0800 (PST)
Generally, the reasons for not including screen shots in Help include the idea that the user is already looking at the screen, so why reproduce it, unless there's a specific problem area that you want to highlight. Also, there's the problem that Help takes up space on the system, and admins generally don't want to lose that space. Including screen shots inflates the required space and therefore lessens the possibility that the admins will even load the help, and that defeats the purpose.
Marguerite
--- On Mon, 1/31/11, Tony Chung <tonyc -at- tonychung -dot- ca> wrote:
From: Tony Chung <tonyc -at- tonychung -dot- ca>
Subject: Re: need advice - writing wiki Help for web app
To: "Monique Semp" <monique -dot- semp -at- earthlink -dot- net>
Cc: "TechWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Monday, January 31, 2011, 11:40 AM
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 mkrupp128 -at- yahoo -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-
