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.
On Mon, Jun 4, 2012 at 11:55 AM, <Brian -dot- Henderson -at- mitchell1 -dot- com> wrote:
> I think the problems with Help that Kevin talks about here should be one
> of the top pet peeves of any professional tech writer. Seems to me there
> are many more examples of bad Help design/organization than good ones.
> So many more that I now consider it a small miracle whenever I encounter
> Help done right.
>
> (Disclaimer: The intensity of my feeling on the subject may be due to
> the fact that I'm currently working on a project that involves reading
> owner's manuals from every automotive manufacturer on the planet.)
>
> -Brian H.
>
> -----Original Message----- From: Kevin McLauchlan
>
> I think one of the things that I really like to see on Help pages is
> orientation.
> Too often, some random help page just jumps into its own little
> procedure, with all kinds of unspoken (unwritten) assumptions about how
> the user/reader got there, and why they need to do what they're being
> told to do right now, and what they should already have done.
>
> As someone who can occasionally be found on this list likes to say
> (might be the title of his blog...) "Every page is page one."
>
> It's not like a book that has Intro and flow and continuity. A person
> entering help might enter it at any point, for a variety of reasons.
> Useful help has to let them know that they are in the right place, as
> well as tell them the actual steps to do what they came for... if it
> turns out they've actually landed on the page they needed... and not one
> that has a similar/related procedure, but which doesn't apply to their
> actual situation... and might actually hurt their situation if they
> don't clue-in in time.
>
> So a help page that includes a procedure should provide the continuity
> by saying explicitly where it assumes the reader is arriving from, and
> maybe what steps they should already have taken or what state they (or
> the product) should already be in, for the current help page to be
> useful.
>
> ON THE OTHER HAND... Â:) Â Your structure and visual conventions should
> show an experienced reader where the meat starts, so they can quickly
> skip over the orientation material, if it's old-hat to them, and they
> just want a refresh on the particular steps of procedure XYZ.
>
> One of the biggest problems I encounter with Help on the web (if only
> Microsoft and Adobe and others were listening) is knowing enough
> background to decide that I'm on the right page for what I need. ÂI
> usually arrive from a Google search, so the specific instructions on the
> page I'm reading might be perfectly accurate and easy to follow... but
> completely wrong for what I need to accomplish. ÂOr, it might be
> completely right, but it just sounds wrong, because it appears to be
> talking about something different than what I thought was my problem or
> task. Glue. Glue is good.
>
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 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://bit.ly/doc-to-help
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as kathleen -dot- eamd -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
>
> Looking for articles on Technical Communications? ÂHead over to our online magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? ÂSearch our public email archives @ http://techwr-l.com/archives
--
Kathleen MacDowell
kathleen -dot- eamd -at- gmail -dot- com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
