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.
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.
Cheers,
-k
From: Becca [mailto:becca_price -at- yahoo -dot- com]
Sent: June-04-12 10:33 AM
To: McLauchlan, Kevin; tech2wr-l; Fred Ridder
Subject: Re: merging Robohelp projects?
The first two classes in the series were very document oriented. We were using Word, and developing procedure and tutorial manuals, so there was a lot of work on content, structure, and so on. The third class in the sequence was learning FrameMaker, and was more process oriented (we were working in teams, where each team member had a specific role, and had regular team meetings, and so on). But all these classes were print-oriented.
This last class is very much tool-oriented. It's assumed we know how to write by now. My main issue is that I know there are different design considerations for developing good on-line help (shorter sentences, more pithy and to the point writing), but I'm sure there are other best practices for help that I just don't know about, and am not even sure what questions to ask.
>From my research into this program and the teacher, the tech writing certificate seems to be looked on very favorably in the local community, and has a good reputation for turning out competent writers. I came into this program having 20+ years experience writing policy and procedure manuals, but with a 6 year gap between now and when I last worked, so I'm looking for things that are very different than the average student is.
-becca
-------------------------------------
"Grant us, in our direst need, the smallest gifts: the nail of the horseshoe, the pin of the axle, the feather at the pivot point, the pebble at the mountain's peak, the kiss in despair, the one right word. In darkness, understanding."
Paladin of Souls (HB page 35), Lois McMaster Bujold
________________________________
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: Fred Ridder <docudoc -at- hotmail -dot- com>; "becca -at- di -dot- org" <becca -at- di -dot- org>; "techwr-l -at- techwr-l -dot- com" <techwr-l -at- techwr-l -dot- com>
Sent: Monday, June 4, 2012 10:16 AM
Subject: RE: merging Robohelp projects?
Hint to Becca:
The brightest, go-getter-est people in your class have
probably found out pretty much what you have, to get the
task done... but they've written up the process and published
it in their blogs, so they will have some CONTENT to show
to prospective employers. Nudge...... nudge.... '
If you look back in the archives of this list, you'll see
where many of the members are hiring managers, and almost
uniformly, they value the nitty-gritty skills of techwriting
over the ability to use a specific tool.
Fred and I are really hoping that that is just ONE class
in your curriculum, and that most of the others have to
do with actual research, organization and writing.
> -----Original Message-----
> From: Fred Ridder
>
>
> Becca wrote:
>
>
> > These are just demonstration projects, showing that we know how to
> use features of the tool. I don't think we're being graded on content
> at all.
>
> Seriously?!?!?
>
>
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
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
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
