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.
Keith...you aren't going to create the best documentation ever...nothing having to do with your abilities...I'm sure they're fine. You can't because everyone has a different understanding of what the best document would look like. You just have to make sure thatg it meets the pictuere in your manager's mind.
IBM thinks they create the best document. Cisco thinks they create the best document. I think I create the best document. Know what they have in common? Nothing.
Having a faily good picture or a good handle is not acceptable because nobody else can see that picture, and without them seeing it, you cannot get consensus that they agree with you. You need a rock-solid document spec with well understood requirements and expectations.
and good luck
John Posada
Senior Technical Writer
"They say everyone needs goals. Mine is to live forever.
So far, so good."
----- Original Message ----
From: Keith Hood <klhra -at- yahoo -dot- com>
To: John Posada <jposada01 -at- yahoo -dot- com>
Cc: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Saturday, July 28, 2007 2:44:44 PM
Subject: Re: Examples
John, thanks for your concern but the picture isn't
quite as grim as you think.
As for user personae - I've got a fairly good picture.
I started on this project by spending several days in
the operations shack, watching and listening to the
operators using the old version of the system. I have
had some interviews with a couple of the older
operators and I think I have a pretty good handle on
their concerns. I need to get some more information,
especially from the newer operators who aren't as
familiar with the system, but I really think user
definitions are covered. There's really only two user
classes and one function that is limited to higher
level users, so this area should be no particular
problem.
A lot of the preproduction I already have kicked. All
the screen captures are already done - made them for
use in the FRs. I have experience doing all the types
of docs I mentioned, and I have a lot of docs saved
from previous work that I can use as templates - all I
need to do in order to create the frameworks for the
user guides in this project is open old files, change
the identifier info (logos in the headers, company
name, etc.), put the right front matter on them, and
save them under different filenames. I figure the
hardest part of the production phase for the user docs
will be the cross-references. I have already worked
out the topic list and the organization of all the
docs.
(Ever use a shareware tool called Freemind? Really
great for layout out document frameworks and things
like that.)
A whale of a lot of the content is already available
in the use cases and functional requirements. This is
the first time in my life I worked on a software
development project where the design documentation got
done first, and the near-finished product follows that
documentation almost to the letter. Most of the user
procedure instructions can be lifted straight from the
use cases, and the reference material from the FRs and
the performance requirements. I know we usually have
to shoot at moving targets and this project is no
exception, but at least this time I don't have to try
shooting while I also have to run behind the target to
stay in range.
Unlimited budget - no, the budget is he pays the
number of hours I bill. No overtime, but if I work 80
hours a week he'll pay it.
And I am pretty sure making the stuff live up to his
expectations should be possible. I've had enough
contact with him about my work, and been involved in
conversations when he's been talking with the
developers about their work, that I'm sure I what his
real concerns are. He mainly wants that he doesn't
have to spend any time explaining to any of the
operators or their supervisors how the system works.
He's concerned that later on he'll be so busy with
other projects that he won't remember enough about
this system in order to explain it properly. So far my
work has been good enough that I've got a fair amount
of credit in his estimation.
--- John Posada <jposada01 -at- yahoo -dot- com> wrote:
> > other sources. My boss said that he wants the user
> > guides to be the best in the world, which, knowing
> him
> > is not all that rhetorical.
>
> Keith, In all seriousness, you have my condolences.
> Why? You are chasing a picture in his head and
> you'll never live up to it. Anything you do, he's
> going to compare it against that picture and you
> can't. Every document feature you implement he's
> going to compare it against something he might have
> seen that caught his attention, but doesn't know how
> difficult it was to implement..
>
> Instead of asking us for examples, ask HIM for
> examples, though chances are he'll never give you
> any because he's never found a perfect document. You
> have another problem in that you have to follow what
> I imagine is a very regulated industry and many
> times, what is "best" conflicts with what they
> require.
>
> Another question...he wants unlimited quality,
> breath, and scope. Has he given you unlimited budget
> and access to unlimited human resources?
>
> > He also said he wants the
> > user docs to explain to the user everything that
> can
> > possibly be explained about the software. It
> should
>
> For who? Have you defined the perfect user persona?
> Have you defined on paper exactly what that user
> does? Reason I'm asking is that a document for a
> user is different than a document for an
> administrator-type person.
>
> Hate to say this, but this is the best definition
> for failure that I've ever seen. I know this wasn't
> what you were lookikng for or that it doesn't even
> answer the question...I just had such a strong
> reaction to his request that I wanted to pass it
> along.
>
> John Posada
> Senior Technical Writer
>
> "They say everyone needs goals. Mine is to live
> forever.
> So far, so good."
>
____________________________________________________________________________________
Shape Yahoo! in your own image. Join our Network Research Panel today! http://surveylink.yahoo.com/gmrs/yahoo_panel_invite.asp?a=7
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
