Re: Requirements from Development? - longish reply

[Barbara Karst-Sabin <Phillinion -at- AOL -dot- COM>]

Before you worry about anything else, you need to establish doc templates and
standard doc plans to use as your basis.  If your company had these before,
they should be adaptable to this new environment.  Whethere you're talking
online or hardcopy, you will still need the same types of information
structured in a similar fashion, so hardcopy templates can still give you a
structural guide for online docs.


In a message dated 98-06-26 11:35:42 EDT, colleen_adams -at- MEDISPAN -dot- COM writes:

<< Ideally, for the GUI apps, I'd like to at least have a functional spec with
 screen shots and minimal text explaining some of the features--is this too
 much to ask of development? (Besides the fact that we'd like to talk to
 some users, which I'm getting closer to doing...) >>

 Otherwise, a requirements spec may also suffice (containing some info
 on the tasks the user will perform)?

Well, if a product is going into development, you should have at least the
requirements spec and probably the functional spec also.  Those and basic doc
designs should allow you to make up a template or framework for the documents,
based on standard doc plans.
              In my last job, the tech writer was part of the development team
and had the chance at team meetings to ask questions and clarify issues of
content/functionality in that forum.  This was very good, because the kinds of
things I needed to know to get started were often things that the SMEs hadn't
even thought about but needed to consider.  Don't know what your situation is,
but if you can participate in this way, it will be a big help.  Also, once you
have some kind of outline or low level doc plan you feel happy with, sending
it to the development team members will help them to see what you need from
them.  They might also see that they have information which needs to be
covered but which has not been built in.  A good thing all round.


<< How much time do you spend interviewing SMEs in the very beginning?>>

It's probably not too useful to spend a lot of time interviewing until you
have the framework or skeleton so that you can start deciding where things
will go and start filling in your gaps.  Although this is very sketchy, it
will show you where your info shortfalls are.  You need to know not only what
the product will do, but you need to know things like platform (for system
requirements) and associated/required hardware or applications which are in
addition to the basic platform, so you have some idea of whether or not
your're going to need to worry about configuration instructions, pinging the
system, and so on.  All that should be known upfront and will give you a good
start on your docs.


<< Currently, we rely too heavily on our SMEs to initially author (especially
 when the audience for the doc is not end-users, but programmers). >>

That's kind of a cultural thing.  My first tech writing job, the SMEs "wrote"
the documents, then the tech writers attempted to put that into some form of
understandable language.  Fortunately, engineers are quite a bit more literate
now than they were then.
             One problem with having the SME do the initial writing is that
they don't have any clue as to what the end-user really wants and needs.  I've
seen this over and over again.  They design a database, and it's nearly
unusable because the info is not stored or retrieved in any way that the user
would wish to do so.  They write instructions for using an application or
piece of hardware, and they leave things out which are self-evident to them
but not to the user.
             I've been in the position of basically starting from square one
on several occasions, but I've always found that even a poorly matched
template gave me something to build from (or maybe it was just having
something concrete in front of me gave me the confidence to dig in ;+).


<< I'd like to hear what some of you real veterans out there require.  You
 can reply offlist; I'll summarize if there's interest.  >>

So much depends on the skills of the SME and the technical background of the
tech writer.  I've worked in so many different environments and had to learn
so many new technologies, that I've gotten used to starting from scratch, but
I'll admit it can be a very daunting prospect.  I realize that you're used to
working in a medical environment, so perhaps the API, GUI etc. is new to you,
but they do really follow the rules for most documentation.


Hope some of this helps,

BJ