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.
> --- John Fleming <johntwrl -at- hotmail -dot- com> wrote (in part):
> >
> > As a personal observation of procedure writing, when
> writing a procedure,
> > make sure you include all the relevant information needed
> by a person to
> > complete the task. You will need to emphaisize the what
> rather than the
> > why.
>
> John's advice is really good. To which I would add one other
> small, little
> thing. Don't accept a procedure from someone else and simply
> put it in your
> document. TEST IT. In my experience, the biggest problem with
> procedures is
> that no one ever actually tried to do it.
>
> Do the procedure, and you'll find out what's missing that a
> user will need.
Sometimes, the procedure just plain won't work (it or the
program are literally broken), or it needs something to
have been set elsewhere during setup, or during an earlier
procedure.
But, the number one reason a procedure usually fails (IMHO)
is that it requires a decision for which the user is not equipped.
They don't have the background to realize the implications of
certain choices, so they have been taking the "safe" way by
accepting the default, but now they arrive at an option that
gives the result they desire, only if they had made non-default
choices at earlier steps.
Or, the developer and writer have gone through it with their
eyes closed so many times, that they don't even imagine
the mindset of somebody from a different background who
would not know what these terms really mean... or who would
have met (and used) terms in other situations, where they carried
different meanings.
I think every instance of Help should have every instance of
even the most faintly jargon-ish words hot-linked to their
extensive glossary meanings (which in turn are cross-linked).
HMMMMMM....
Here's one...
Have you ever started looking through a Help or a HowTo or
a web page that did have lotsa links, and eventually you got
so far away from your entry point that you forgot what you
were about? Or, have you ever gone down a heirarchy, then
backed up several pages and gone down another (or two, or ten)
only to not be able to find your way back to the first one,
that -- after all the lookin' -- actually looks more promising
than others?
We need a way to install "Way Points" in navigation. Does it
already exist? Bookmarks don't quite do it. It should be
something that (on your local system) attaches to a particular
URL so that whenever you arrive at that URL, you see a
pointer. So, if I went to page A then page B, then C, D, E, F,
G, H, I, ... and then went <Back>, <Back>, <Back>... to page C,
I could put a marker at C that would remember all the <Next>s
down to page I.
Then, I would go from page C to page Delta, page Epsilon
and page Phi (reading and digesting a lot of material) before
deciding that this route is not as promising as an earlier one.
So, I go back to page C. Now, I can try to recreate the earlier
path, slogging through a half dozen vaguely familiar decisions
per page, and I may get lucky. And, by the way, WAS it actually
page C where the earlier promising branch took place? It's been
many pages and many words. Perhaps the branching was at Alpha?
But wait! Since I left myself a waypoint, I see a visible
reminder as soon as I arrive at page C (so now I know it wasn't
Alpha). I click my waypoint, which brings me instantly down the
earlier path D, E, F, G, H, I...) that would normally have been
deleted by my intervening greek episode).
Ok, I ramble. I was thinking out loud. Does that functionality
exist? Should it? Would it be useful to any kind of brain except
the kind that works the way mine does?
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
