Conference 7.286::digital

Ref. .0
>    o  What is your working relationship? Are you in the same group? If
>       not, by how many levels of management are you separated? What effect
>       does this have on how you do your job?

T&N Publications is a part of NaC, but does support other groups as well. Having
spent close to 10 years with what is now CUIP, I've seen what it's like to have
a separate documentation organization, not directly owned by the engineering 
group it supported. 

The major advantage to having a separate documentation group, IMHO, is the 
opportunities for professional development for the doc folks. Writers who work
within engineering groups often report how difficult it is to keep current with
technology and methods for information analysis and presentation. While eng. 
managers keep track of courses and conferences for engineers, they would not
often do the same for Seybold Seminars, for example.

There are long-standing issues regarding coordinated acitivities on any project.
In CUIP, the chain of command doesn't converge until somewhere around the Sr.VP
level. It took a lot of shouting to get issues resolved. Of course, what're 
seeing now is that all VPs and senior manager are having a tough time gaining
control over their organizations; common management probably has about the same
effect on company direction as does common parking lots.
    
>    o  How involved are engineers/documentors in the process of producing
>       documents/products. Should it be more? Less? Are there holes in this
>       involvement? What is your role in getting the other's work done?
>       What should it be? What is the other's role in getting your work
>       done? What should it be?

Increasingly, documentors are being asked to make contributions to the UI of 
their products. To do this, documentors are needed to develop new skills and
to use new tools to get their ideas across. GUI profiling tools, such as VUIT, 
make it possible for documentors to get their ideas into forms that are more
readily digestible by the person building product.

The holes in these processes are many. There are not yet CASE-level tools for
documentation profressionals to design and build the information packages that
accompany a product. There's a great deal of territorialism on all sides. (The
application ought to be able to generate all of the reference material from the
source, sparing everyone the tedium and typos of recreating the Foobar Reference
Manual. 

More later. Long notes typically aren't read.

    The group I'm with now doesn't currently have support from real
    documentation people. We did once. It was expensive. Both in time
    and in funny money. There were a number of reasons why things didn't
    work out so well but I'll get into that later. I previously worked
    in an other group that had lots of real writer support. It worked well
    there.

    In my current group the writer we had we contracted for with a writing
    group. I believe our management chain joined at the VP level. Not below
    and possibly higher. I don't believe that was a problem. We all got 
    along well with the writer and I believe she received most of the
    support she needed at the time from engineers.

    The same was true with the other group I worked for.

    When things didn't work out I believe it was because of problems with
    schedules. Writing the documentation often seems to take longer then 
    writing the code. If there are known cut off dates for a product the
    cut off for new functionality has to be a while before the
    documentation has to be ready. Otherwise the writer may never catch up
    and a product will sit around waiting for the documentation. 

    I wrote both some software and the user documentation for a major tool
    my group did. One of the things that became clear to me was just how
    much work went into documenting "one little qualifier." It was often
    as involved as writing the code. And other engineers often didn't 
    understand that.

    I believe that engineers should be pretty involved in the documentation
    process. They should explain what a feature is, what it does, and how
    and why someone might use it. They should also review closely any
    documentation written for products they use. They should also take
    it upon themselves to help generate examples for the documentation.

    Also I believe that we as a company should be more involved in 
    automating the documentation process. For example, I wrote a book
    that included a section of DCL commands used. The commands were 
    defined in a CLD file. Going through and manually picking out all
    the verbs, parameters, qualifiers, and keywords and figuring out
    what went with what was a royal pain. With several different engineers
    contributing to that file getting things clear from them was not 
    always easy. But hey, CLD files are meant for a computer to understand.
    Why is there no tool to read a CLD file and output some sort of
    SDML file that a writer can use as a start? (There may be on other
    then the one I'm trying to do in my spare time out of self defense
    but I doubt it.) I'm sure there are a lot of other tools that are
    just as needed but writers don't know what can be done and engineers
    don't know what needs to be done.

    In any case if we can lower the need for documentation people to ask
    about things engineers thing are trivial ("what are the qualifiers
    for the foo command?") and allow them to get to the meat ("What does
    the /ABORT qualifier on the FOO command do?") we can probably improve
    both productivity and relationships.

    Recommendation. Make having written at least one significant piece
    of end user documentation a requirement for making Senior engineer
    and appreciation for and a willingness to help real writers will
    increase by leaps and bounds. :-)

    			Alfred

A couple of comments from an engineer.

1.   Tech writers often have an inadequate grasp of the underlying
     technology.  Too many times, writing the documentation 
     consists of prettying up the functional spec (which is 
     an engineering document and therefore isn't aimed at
     the same audience).  A much deeper understanding is
     required.   A possible contributing factor here is maybe
     that (it seems to me) tech writers are shuffled around
     projects like interchangeable parts.  To be a good tech
     writer requires that you understand the externals of the
     software about as well as the engineers who are building  
     the thing.  How else can you explain it to users?

2.   Your average engineer doesn't seem to have any idea how
     to review manuals.   Just looking for "mistakes" in the
     information is not good enough; one needs to examine
     it for consistency, completeness, applicability to the
     job, etc.  This *is* the responsibility of technical
     reviewers - only they can tell whether this book contains
     what's needed to manage the software, use the programming
     interface, etc.   Furthermore, Y. Average Engineer has been
     taught that reviewing manuals is something that you do if
     you've got nothing better to occupy your time, and that
     if you don't quite get around to doing it, then it doesn't
     really matter, because it's not your problem after all, it's
     the writer's worry.

    Re: . -1
    
    I'll second item number one: a tech writer must have an adequate
    grasp of what he is writing about.
    
    I've had a tech writer try to write a software manual and not have any
    idea of how to use the software.  Trying to explain something not
    understood usually doesn't work too well, and it didn't.  In spades.

    This was written several years ago, but it is germain 
    to the topic, so I offer it for consideration:
    
    ==============================================================
    
    Within the profession of technical writing, it is a common and 
    recurring complaint that writers are treated as "second-class 
    citizens" by the engineering community -- that we "don't get 
    no [professional] respect."  At one time or another, this complaint 
    has been voiced by everyone in publications.  But is a lack 
    of "professional respect" the real problem?
    
    With the advent of the PC, a new era in technical communications 
    began:  For the first time, computer documentation had to address 
    naive users.  This challenge instilled a new emphasis on understanding 
    the role of documentation from the user's perspective, as opposed to 
    the lab technician's.  In adopting the user's perpective, we have 
    come to realize that documentation plays a powerful role in allowing a 
    user to access the full capabilities of a system -- any system, not 
    just a PC.  
    
    As a result of our enhanced awareness, the method of documenting 
    products has changed tremendously over the past five to ten years.  
    Where once a technical manual was deemed sufficient, now documentation 
    sets include user's guides that supply examples across a spectrum 
    of complexity; tutorials specifically designed for use in "hands 
    on" environments; user's cards for quick reference to commonly 
    used procedures or commands; and the list is as extensive as the 
    demand.  In short, documentation tries to focus on all the perspectives 
    from which a user might approach a system, and these "perspectives" 
    are organized to present information that coincides with the natural 
    order of a user's expectations.  
    
    In a very real sense then, documentation can be viewed as the 
    "user-thought" layer of a network architecture.  If you will, 
    documentation establishes communication protocols which interface 
    with the network through the digits of a user's hands.  When seen in 
    this light, it is clear that creating user documentation is an 
    engineering function in which real design decisions must be made -- 
    decisions which greatly impact the usefulness and marketability of 
    a system.  
    
    This truly is the role of technical documentation, yet the 
    myth persists that creating technical documentation requires nothing 
    more than a passive response to the development of some new product:  
    "The product gets built, then you write a report."  This is an 
    old prejudice, and one which squanders opportunity and bruises 
    professional pride.
    
    In the ideal development environment, engineers and writers work together.  
    As an engineer develops a new function, the writer might say, "Okay, that 
    sounds good, but if we do it like that, the user will have to do X, Y, 
    and Z, and that would be awkward.  Let's find a way to cut out those 
    steps, and the user will have a much easier time."  Conversely, the 
    writer might word a procedure in such-and-such a fashion, and the 
    engineer could respond, "Hey, that's too many examples.  Remember, we're 
    designing this thing for a sophisticated user."  Back and forth the 
    communication would go -- from the outset of product development -- and 
    when differences remain, both writer and engineer would defer to the 
    other's expertise.  But the process of communication would have a 
    synergistic effect, and the final product would be more cohesive and 
    functional.
    
    Perhaps this scenario sounds too simplistic, but in the past five years
    a major competitor of our's --  a certain blue giant -- has issued a 
    corporate wide "action-item" to implement closer development ties between 
    writers and engineers.  Their decision was based on several years 
    of research and testing, and according to independent evaluations, it 
    has achieved outstanding results.  Some people might take exception to 
    this precedent, saying, "We don't do things like they do.  End of 
    discussion."  But that's like saying our terminals don't use keyboards.  
    The fact is, even though we have different corporate philosophies, we 
    do a lot of things the same way already.
    
    Although our development methods are becoming more synergistic, 
    we have yet to realize the ultimate goal of the distributed processing 
    philosophy -- distributed development.  As we see our corporate 
    philosophy come to fruition, we will also begin to realize the full 
    potential of distributed development.  
    
    In a mature distributed development environment, writers and engineers 
    will not only work together to develop products, but the technical 
    communication department will become the communications repository for the 
    development community.  It will gather, organize, and distribute
    information accross the development spectrum, thus ensuring the 
    timely exchange of consistent information between related development 
    efforts.

    
.5>  Perhaps this scenario sounds too simplistic, but in the past five years
.5>  a major competitor of our's --  a certain blue giant -- has issued a 
.5>  corporate wide "action-item" to implement closer development ties between 
.5>  writers and engineers.  Their decision was based on several years 
.5>  of research and testing, and according to independent evaluations, it 
.5>  has achieved outstanding results.
    
    Do you know specifically how these "closer development ties" were
    implemented?
    

"Documentation" and code must merge into a single entity.

"Writers" must be replaced by, for lack of a better term,
"information engineers".

Every time we feel compelled to write a list of instructions
intended for a human reader, we should consider that a failure.

The mental distinctions of the end-user, between "using" an
application and "reading about" it must blur, and dissappear.

All of the numerous exceptions to these statements are not
what matters; what matters in the immense field of opportunity
to which they _do_ apply.

The competition has been doing this for some time; it's yet
another race in which DEC is far behind.

- greg

ps: I hope it is obvious that I'm not talking about narrative
    material, textbooks, contracts, non-computer/hyper-media
    based advertising/sales/marketing material, etc.

       A couple of comments from a doc person:

       The problem with the thinking in .3 is the following notion: 

           "To be a good tech writer requires that you understand the
           externals of the software about as well as the engineers who
           are building the thing.  How else can you explain it to
           users?"  

       While I'd quickly agree that a writer has to fully understand the
       externals of any software being documented,  the statement seems
       to assume that the purpose of documentation is to explain how the
       software works.  A 1st-rate software manual is not one that
       describes how s/w works; instead, a good software manual is one
       that explains how users can accomplish their tasks by through the
       use of the software.  
       
       The keys here are understanding what the user wants to
       do, and how the software can be used to accomplish it.  No one
       wants to use a Backup utility because it's a backup utility;
       people want to be able to recover from a disk failure or unload
       savesets or restore a directory tree that inadvertently got
       deleted. 

       In order to provide a good technical review of documentation, a
       reviewer must know not only how the software is built, but, more
       importantly, the ways in which users are likely to apply the
       software.  A reviewer who concentrates on whether every bell and
       whistle and qualifier and error message is included provides an
       almost meaningless review compared to the reviewer who  focuses on
       the usability of the documentation.
       
       --Don

    Since I gave a negative tech-writer story a few notes ago, I'll give a
    very positive one as a counterpoint.

    Bill English contracted to write the Architecture Manual for the PDP-10
    systems. At one point he read the microcode listing for a new
    instruction and documented it accordingly.  When we reviewed his text,
    we said, "It doesn't work that way, " to which he replied, "Oh yes, it
    does!"  He was right, and we had to fix the bug.

    
    Re .7: How do you relate your opinion to, for example, explaining how
    to use write programs using VAX C, or how to implement a transaction
    processing system using VAX ACMS?
    

What the engineers do is often mysterious to the writers.
What the writers do is usually just as mysterious to the engineers.

"Easy-to-use" manuals are the hardest to write.  If you're writing directly 
for an engineering audience, it's much easier, and you don't always have to
have a deep understanding, because the reader can often supply that, given 
the facts in an appropriate form.

The user interface, marketing documents, conventional documentation, training,
and online help are all part of the product information set and ought to be
conveying the same message, which is how to get this thing to do what you want
it to.  And .7 by STAR::ROBERT points the way to go with this.

The demands on documentation change enormously depending on the product and 
the user.  What's appropriate for an internals manual is gibberish in an 
end-user manual.

>What the engineers do is often mysterious to the writers.
>What the writers do is usually just as mysterious to the engineers.

That's certainly true, although the engineers aren't always conscious of this.

As an ex-engineer who's spent a heck of a lot of time defending writers, this
topic in general tends to be a hot one for me.

On the one hand, it's easy for everyone to agree on the first point above.  What
I don't always see agreement on (at least on the part of the engineers) is that
the writers have a pretty complex job, too.

Where the engineers create problems, the writers are left with the unenviable
task of explaining those problems to the customers, and doing so in such a way
as to make it sound logical, reasonable, and an explicit goal (not to mention
something that someone would want).

Well, that's sort of tongue in cheek, but the problem's real:  It can be hard
to document some software, but all I hear is a bunch of squealing on the part
of the engineer that the writer isn't smart enough.  Often, this comes from an
engineer who has a very hard time making it from one end of a sentence to the
other without making some serious grammatical and spelling errors.

It seems easy to blame the writer for a bad manual, but what I rarely hear is
accountability on the part of engineering for creating something that's so hard
to document.

IMHO, documentation SHOULD have veto power on the external presentation of 
anything they're tasked to document.  After all, if the writer can't make sense
of something, or can't find a reasonable way to put it into words, what the 
heck do we expect our customers to do with the stuff.

Over all, I get sort of tired of this whole "second class" attitude.  
Unfortunately, it's bought into all over the place. 

All I need to do is try to defend a group of writers in front of a group of 
engineers and what I inevitably get in response is an engineer holding up the
worst writer in the group as being an example that represents the entire 
group.

But, it cuts both ways.  Maybe I haven't been listening well enough, but I 
haven't heard too many writers pushing back on engineering.  It's as if many
of those writers have themselves bought into the "second class" myth.

In the end, it all comes down to: engineering is a hard job, and so is writing.
Anyone caught up in delusions that their job is harder or more important than
someone else's (like engineering vs writing) is more of a liability than a
help.

    
    Re: .8 and .10
    
    Different problems require different solutions. Don Topaz is right in
    that some software is very task-oriented and its documentation can be
    of the cook-book variety.
    
    Other software (compilers, ACMS, some database systems and query
    languages, doubtless others) needs to be described in terms of some
    conceptual model the user must acquire in order not to be surprised
    by the software's operation. You can't really learn a computer language
    from a task-oriented cookbook, any more than you can learn French from
    a Berlitz phrasebook. There's nothing wrong with a phrasebook ("ou est
    le toilette" can be a very useful thing to know) but you will never
    become fluent that way. Fluid, perhaps, but I digress.
    
    Some software doesn't (or shouldn't) need any manuals. And some
    software products actually have multiple and conflicting conceptual
    models "underneath," which makes them impossible to document well.
    
    The documentation is the window through which the user sees the
    product. The best documentation is a perfectly transparent window. If
    you don't like the scenery, that's not the fault of the documentation.
    
    JP

>   <<< Note 1882.10 by WLDBIL::KILGORE "...57 channels, and nothin' on..." >>>
>    
>    Re .7: How do you relate your opinion to, for example, explaining how
>    to use write programs using VAX C, or how to implement a transaction
>    processing system using VAX ACMS?

If by "how to write programs using VAX C" you mean tutorial information,
then I've already excepted that.  If you mean reference information, that
should probably be primarily accessed through the tools you use to create
and edit programs, for example structured editors like LSE.  Not manifest
as "books" be they on paper or electronic, and not thought of as works
of words.

I believe that when this is done properly, there will be little material
that is not covered by tutorial books with titles like "Basic Programming", 
"How to Program in Low Level Implementation Languages (like Bliss, C, etc.)",
and the reference material (syntax, system call templates, examples)
which are intergrated holistically with the program creation tools.
Not that the second book title is not a list of books, but ONE book that
covers a variety of languages and is probably most often seen in schools.
Such books may be funded by vendors, but are probably not written by
vendors.  They may be based on internal spec's made available to authors
but not generally published.  None of these books are what we think of
as technical documentation today (at least at DEC).

For implementing a transaction processing system I would again expect
the subject to be divided between very non-product specific but very
detailed and helpful tutorial books, and extremely technical material
that might appear in the form of libraries of calls, moderately large
sample programs, higher-level language generators.

But all that said, my first response is really to point out that the
examples you've given are for material that would be aimed at a very
small, highly technical audience; not the 99+% of computer users who
would never call themselves "programmers" or "engineers".

Computers _are_ a more significant invention than movable type;
it has served us well for centuries, but we are ready to move
onto enormously more powerful paragigms.

- greg

    "Write the documentation first."  [Then write the code.]
    
    A bit glib and somewhat idealistic, but this changing of the starting
    point could get us out of the trap of trying to explain how the
    software works, which is from the perspective of the engineer.
    
    In my space, translation of documentation is a big issue.  To that end,
    my one-plus to the slogan becomes: "Write the foreign language (e.g.
    Japanese) documentation first."  Maybe a bit far-out for a New England
    company like Digital, though.
    
    --Simon
    

    RE: documentation
    
    I wish I still had a copy of the the old PDP-11 DIGICALC user's manual 
    (from a 3rd party vendor).  It was FANTASTIC!!!
    
    Why?  Because it was "chatty".  Reading it was like sitting and
    listening to your best buddy explain to you how the thing worked. 
    Complete with smart-ass wisecracks!  Fantastic!
    
    They are had a "demo on paper" that was equally impressive.  No dry
    lifeless technobabble here -- it was the soul of a really good sales
    support person reduced to a piece of paper!
    
    Both were EXCELLENT mold-breaking concepts of how to tell someone about
    the product.  You actually ENJOYED reading it!
    
    -- Russ

I recently worked with some tech writers on some documents. I was 
asked to give them a description of how to use the tools I had
written.  I expected it to be rewritten; it was put in the manuals
essentially as I had written it. Therefore, I feel like I'm both a
tech writer and an engineer.

One problem we had was that the writers did not have the background
information that we expected of the readers. The tasks (compiling
and installing fonts on various Unix systems) were intended to be 
done by system managers. The writers were completely unfamiliar with
Unix. Therefore, we had to spend more time than we would have liked
giving them the background that the readers are expected to already
have. To use an earlier example, it helps if someone writing a C 
reference manual knows how to program in C.

Our quality group reviewed the manuals by actually following the
procedures given and making sure everything worked as documented.
This is very good. However, while this worked fine for general
user documents, that group also lacked Unix expertise, and we had
to work closely with them. Ideally, the reviewers for documents like
this should not come to the engineers unless something does not
work as described. The documents should be reviewed by someone with
the same background as the target audience.

   Re:     <<< Note 1882.17 by ROYALT::KOVNER "Everything you know is wrong!" >>>

It sounds like somebody violated Dick's rule number 17.

                  "If you're going to teach tricks to a dog,
                   you'd better know more than he does!"
                   
Seriously, picking writers who don't know the intended audience
is a management mistake and it sounds like you paid for it.
Granted, one can't always find exactly the talents needed, but
you have to make up for it by providing a simulated audience.
Maybe you were it?

Dick

re .8 (Mr. Topaz)
    
    >   The problem with the thinking in .3 is the following notion: 
    >
    >       "To be a good tech writer requires that you understand the
    >       externals of the software about as well as the engineers who
    >       are building the thing.  How else can you explain it to
    >       users?"  
    >
    >   While I'd quickly agree that a writer has to fully understand the
    >   externals of any software being documented,  the statement seems
    >   to assume that the purpose of documentation is to explain how the
    >   software works.  A 1st-rate software manual is not one that
    
    Well, that's not what I meant (which may be why I'm not a tech
    writer).    I said "externals" in order to exclude the details
    of what's going on under the covers -- how it works.   What 
    I thought I was implicitly including was information about
    how to use it.   To do that successfully requires much more than
    being able to say what the commands and qualifiers are; to
    cut a long story short, and to avoid telling you your own
    job, you need to *be* a user of the software before
    you can teach someone else to use it.
    
    

general point:  

Why has this discussion focused so much on software
documentation and so little on more general documentation?
I re-read the base note, and there was no mention either way, hw vs. sw.
We DO create hardware products and documentation too,
and for products that our customers actually see and touch,
like the printing and display products created in my building.
There are elements in common across these divisions, but there are 
differences too.

re: .13, transparent documentation

I don't know quite how you meant it, but "The best documentation is 
a perfectly transparent window" is a terrible metaphor!
The documentation should add value, and be PART OF the scenery.
It is, after all, PART OF the product, and the customer is paying for it.

- tom]

    
    Re: .20
    
    Analogy and metaphor can always be taken too far, at which point they
    break. Yes, documentation is part of the product, and "window dressing"
    (there I go again), as a way to make something superficially pretty,
    has been around so long that it is a cliche.
    
    My point was that you can't fix a bad software product with
    documentation. Not even if you use rose-colored glass in the windows.
    
    Sure, documentation is a big part of a product and the customer is
    paying a lot for it. But we should not kid ourselves that this is what
    the customer wants. My guess (based on 21 years in the industry and 14
    in technical writing) is that the vast majority of customers would
    never read any documentation if there was any way to avoid it.
    
    JP
    

    
    As a writer, I work with many engineering groups. I have had groups
    that knew exactly what they wanted, some just want specs converted over
    applying them to an external audience. I have worked closely with
    engineers to provide a layout of the documentation before work even
    begins.
    
    I have noticed these days alot of products are using the same software
    or same chips. If the documentation already exists for a previous
    product, alot is coming from those books and are tweaked to apply to
    the latest product. 
    
    Yes, I agree a writer should be knowledgable, but we work many different
    products for engineering groups and to have people proficient in everything
    is a bit unrealistic. Where engineering may work a product for a year
    or two, I can work 5 or more projects within that timeframe. I feel
    this give me an all around knowledge of engineering groups and the
    products that come out of them because we get funders returning to us
    for work.
    
    I also believe that documentation is a vital part of the product. But
    in some cases, documentation folks are brought in either to early,
    which causes many changes to what is created, or too late, which causes
    a rush to get documentation out.
    
    Mary
    

    re .15
    
    Write the documentation first.  Some form of this model
    may come to pass.  Supposedly, it's a Stone initiative.
    
    Suppose the writers and engineers elaborate on the product 
    requirments and engineering spec to flesh out the user 
    documents -- thorough conceptual design of the "perfect" product.
    Then the engineers use that to write code, and where they hit upon
    snags and have to make changes, the documentation gets "updated" 
    as part of initial development.
    
    Think about it...

    
    I heard an interesting quote the other day, appropos of some
    of this discussion:
    
    "Every page of documentation represents a defect in the product".
    
    I liked it because, while certainly not completely true, it
    captures the sense that we have a ways to go on intuitive
    products and especially on improving user interfaces.
    
    Glenn

    
    .23   I've had this happen, but it was because engineering specs 
    were not signed off when they came out of Phase I review. I
    cannot begin to tell you the problems that happened because of it. 
    
    The engineers I worked with were great, but it was alot of work. The
    book was created and while the spec was still going threw changes, I
    would have to sit and do a page by page review to note those changes.
    This gets costly in $$ and time, especially when you are trying to
    hit a product schedule.
    
    I have had excellent working conditions with all the engineers I have
    dealt with. When a project comes into our group, our unit manager sees
    if we have the resources to do it, then looks at who is available and
    places people on projects. Once we are placed, it is our responsibilty
    to provide the service to the funder and work with them to meet there
    needs. I believe the only time I have to really involve management is
    when the project gets pushed out and we need to coordinate funding or
    if there is a problem that we as a team cannot solve.
    
    But on the most part, I am part of the engineering team and we work as
    a team, and I am there to provide a service to them and to make
    recommendations for documentation.
    
    Mary
    

    I must say I disagree with this phrase in .24:
    "Every page of documentation represents a defect in the product".
    
    It's quite the opposite of .23 and .15's idea of writing the
    documentation first, so that the product is built to spec.
    
    I was a tech writer once upon a time way way back when, and I rather
    liked the saying,
    
    "A bug is an undocumented feature.  A feature is a documented bug."
    
    It is literally true.
        fred

    
    In 17.5 years in this business, i still only go to the DOC's when
    the product has me baffled and frustrated.  I suspect if the DOC's
    were done first, you just might end up with a product that needs
    no explaining.
    
    I have however, recently used award winning documentation for a product
    that can be very confusing and frustrating.  The writers have done a
    splendid job in (perhaps) recognizing this aspect, and i do find my
    frustration rapidly subsiding when forced to go there.
    
    While there are indeed those who approach new things in a planned
    methodical manner (read before use) I suspect there are many others
    like myself, and I believe we should engineer products always with
    the notion that someone is bound to play with something before reading
    the manual.
    
    bob

    re .25 (re .23):
>    book was created and while the spec was still going threw changes, I
>    would have to sit and do a page by page review to note those changes.
    
    You didn't get the point.  When you write the documentation first, you
    change the *code* to match the documentation, not the other way around.
    The documentation *is* the spec.
    
    re .26:
>                    -< the documentation takes precedence >-
    That's the idea.
    
    --Simon
    

    
    	I believe there is a difference between good specsmanship and
    technical writing. Specs, obviously, should be written first. But this
    does not necessarily translate into user documentation directly.
    Replies .7 and .24 make good points about the nature of documentation
    today as well as where we should be directing our efforts now and in
    the future. If the specs incorporate the concepts properly and if the
    design adheres to them, you will eliminate a good deal of user
    documentation, or you will open up a new level of documentation that can 
    depict solutions and possibilities versus theory of operation, repair,
    etc. Although I've seen very good specs, most are at a level which 
    really aren't appropriate for the customer who wants to use versus
    operate their computer. The documentation suffers as a result.
    Fortunately I've seen the beginnings of change in this area.
    	I would also view the code as the lowest level of documentation.
    The spec should direct the code or design to a goal. But the code
    itself must be well documented. For example the comment for a
    particular instruction or the changes from one revision to the next can
    be captured by AUTODOC.
    	One of the biggest problems I see with any information whether it
    be specs, technical documentation, business plans, marketing
    information, sales literature, training material, etc. all of which may
    and should be related,  is a good hierarchical organization and
    interrelationships with other disciplines. 
    	For example, a group of engineers write several chip specs. A
    module designer groups these chip specs into one module spec. A system 
    designer groups the module and device specs into a system spec. All of
    this is done in building block or sum of the pieces fashion, with
    little added value at each step. This approach is of course used by the 
    various documentation groups to provide specific documentation for
    sales, training, service guides, user manuals, etc. And it results in
    problems for many; with Sales usually taking the brunt of the blame for 
    poorly understanding the products. I would rather see each next level 
    of documentation explain just what the new "whole" means versus
    regurgitating the component pieces again. Typically we end up with more 
    volume of material as we go up the information hierarchy but with less
    understanding of the whole; I would contend that this hierarchy should
    be the other way around; each next level provides a clearer picture of
    the solution while reducing or rigidly controlling the volume of
    information. 
    	 
    
    

    
    I'm still grappling with the question. It seems we need several types of
    specs to make the process work. First we need a good methodology for 
    obtaining customer requirements. Next the high level specs_person
    writes up the compromise solution spec since we seldom ever hit upon a
    solution which is ideal for all customers. We then go back to this
    group of customers to see if this compromise is acceptable. If it is,
    we now have the final requirements spec; otherwise we weigh available 
    resources and other business considerations to see if we can break up
    the one entity into smaller customized pieces to meet the customers'
    requirements in which case we have several specs. 
    	But now, even though we have the compromise solution and
    requirements spec firmly in hand, we need another spec which defines
    the direction for implementation; since there may be infinite ways to
    meet the customers' requirements. This would require possibly another
    spec that assesses the human factors issue; namely what is the
    acceptable level of pain to satisfy the requirements, both to us and
    the customers. This would guide our thoughts in "shaping" the solution.
    	Now of course we need a way of bringing these 3 specs (compromise 
    solution, implementation and shaping) with the big picture down to each 
    level that is necessary for complete understanding. That is the
    top-down approach which is sorely lacking today or at least which is
    most poorly communicated. Now we can begin the bottom-up information
    phase which will inevitably have some impact on one of the 3 specs
    (hopefully not the compromise solution spec) because of technology
    issues, problems inherent to top down specs, etc.. Of course we can have
    more changes in either flow (topdown or bottomup) affecting each other. 
    The bottomup flow of information needs to build and add value at each
    step and put controls on the information itself (maybe we need a fourth 
    toplevel spec here defining hierarchy, parallel developments and
    granularity) before it gets out of hand. 
    	So with all this happening when does one get to start the design
    work and what exactly will prevent code/design changes from changing
    one of these specs? Enough rambling, but I think the process is more of
    a very fluid art of compromise and constant negotiation and
    communication with the customers as well as internal organizations, not a 
    rigid science. And crucial to this process is how well we manage the
    flow of all information, not just technical documentation, in order to 
    accomplish the goals without inundating the customer with
    trivia, procedures, tips, etc. The code, specs and documentation seem
    to be secondary to the proper flow and hierarchy of information.
    Something that seems to illustrate this is good revision control
    documents, probably about the most difficult things to create and
    maintain. 
    	Sorry for all the tangents!  

    When I buy software, I expect it to be easy enough to use that I don't
    need a manual.  When I consult the manual, I expect it to be easy
    enough to use that I don't need to go to a training course.  I'm trying
    to design software keeping this in mind.  Often it seems to me our 
    competition is already selling this type of solution.  
    
    Steve

    re .-1
    
    So, when you buy the "turbo-mumblefrotz advanced programming
    interface" you don't expect to have to read anything to find
    out (a) what function calls the TMfAPI provides (b) the parameters
    that any particular TMfAPI function call expects?
    
    
    

    re: .1
    
    Thats great for technically oriented documents.  To be precise and
    correct, I always look up a function's declaration and description
    (unless its putc() or atoi()).
    
    But when I run an office application like ALL-IN-1, and I receive a
    message that I need to hi the <EXIT SCREEN> key, and I can't find one
    on the keyboard, including the 'Gold Keyboard', ....
    
    Get the customer's requirements, write the specs., create the
    application and documentation for the specs., and cross-check during
    development.  We need quality people on the software engineering side,
    technical writing, and project management side that understand the
    customer's needs and can provide a solution with an easy to use User
    Interface.
    
    --- Gavin

>         <<< Note 1882.33 by ALAMOS::ADAMS "Visualize Whirled Peas" >>>
...    
>    Get the customer's requirements, write the specs., create the
>    application and documentation for the specs., and cross-check during
>    development.  

Wait a minute, where's the step "identify and solve the customer's problem?"
It's a whole lot different identifying a solution the customer already has
and automating it than identifying the problems a customer has and 
coupling those to a solution you can supply and sell to that customer.
I suspect the latter is the more prevalent case.
The former is the more likely to need less documentation, which can also
be more intuitive.
We don't have to sell (or train) people on the >concept< of word processing
packages any more - that's become "intuitive."
Selling them (and training them) on the concept and realization of
hypermedia (for example) is a whole 'nother ball game.

- tom]

>>    Get the customer's requirements, write the specs., create the
>>    application and documentation for the specs., and cross-check during
>>    development.

>Wait a minute, where's the step "identify and solve the customer's problem?"
>It's a whole lot different identifying a solution the customer already has
>and automating it than identifying the problems a customer has and
>coupling those to a solution you can supply and sell to that customer.

.33 development.  We need quality people on the software engineering side,
.33 technical writing, and project management side that understand the
.33 customer's needs and can provide a solution with an easy to use User
.33 Interface.

    That step was implied in understanding the customer's needs and
    providing a solution.

>I suspect the latter is the more prevalent case.
>The former is the more likely to need less documentation, which can also
>be more intuitive.
    
>We don't have to sell (or train) people on the >concept< of word processing
>packages any more - that's become "intuitive."
>Selling them (and training them) on the concept and realization of
>hypermedia (for example) is a whole 'nother ball game.
    
    I agree.  I was comparing technical products such as compilers,
    programming libraries, etc., to generalized applications (word
    processing, Notes, etc.).  More content of how a process (i.e.,
    solution) operates should be placed into the manual vs. how to run the
    application.
    
    Enough rambling for now,
    
    --- Gavin

    I have worked on both the engineering and documentation sides of
    product development.  The most effective technical writing environments
    for me have been ones in which writers:
    
    	. Were considered members of the project team, and
          their contributions viewed equally,
    
    	. Were physically located in close proximity to the
    	  product development team, and participated in all aspects
    	  of the development cycle, 
    
    	. Had the time to become involved with the target of their	 
    	  documentation effort, for example, use the product, read
    	  specs and product data sheets, or in some instances	  
    	  actually read code (do I dare say the word play?), and  
    
    	. Had the necessary hardware, software, and documentation to
    	  complete their tasks successfully.
    
    Charles M. Norton
    PATHWORKS UI
    PCSG MS Windows and Applications
    LJO2/H4 -- Office A45 
    226-2597
                                  

    I heartily agree with .7's
    
    �Every time we feel compelled to write a list of instructions
    �intended for a human reader, we should consider that a failure.
    
    But that doesn't mean I buy all this `write the docs first' stuff.
    A lot of engineers would let that happen over their dead bodies.
    A lot of writers (I'm one) don't see it as a realistic goal.
    
    As .1 said, both writers and engineers are spending more time on
    the UI, and I believe _this_ is where the `Stone initiative' is
    leading - reducing (ultimately, to zero) the time lapse between
    writers' and engineers' contributions to a project. And when this
    gap is annihilated, it will no longer be appropriate to talk about
    writers and engineers as distinct beasts. The machines will do
    the boring bits. .1's vision of reference manuals that write
    themselves isn't a pipe-dream - it should be only a few years
    away [
    	  although it'll be more than that before everyone in the
    	  corporation is letting it happen - as an example, there
    	  is a simple trick for generating a graphic for a data-
    	  structure from a text description; the number of writers
    	  I know of who use it is tiny
    	 ]
    Probably software that both has an intuitive UI _and_ is entirely
    self documenting in all other respects is a bit further off.
    But I believe it'll happen.
    
    b

    Re: .15
    
    >"Write the documentation first."
    
    This is how Wang developed their word processing system released in
    1976.  Not a bad model.  It certainly epitomizes the idea of
    market-driven development -- figure out what the users want the thing
    to do, and then built that.

    The idea that every page of documentation represents a flaw in the
    product makes for a nice slogan.  But can you name any computer products
    that have no documentation?  By that I don't mean no printed manual but 
    many screens of on-line help -- I mean no documentation.

    re .39
    
    I knew technology had gotten out of hand when my telephone came with
    a users guide - and I needed to read it in order to use the &%(&#
    thing......
    
    Bill

    Hi, Steve:  (Note 1882.39)
    
    I agree with you about the nice slogan.  But I have to name a computer
    product that I can use without documentation.... The copier here at
    work. The user interface is great.  I can even clear jams without
    refering to the documention.  The front panel displays the jam
    area, the stickers inside the machine tell me what to do.  
    I wish all hardware were that easy to run.  
    
    Kathy

        Re: .29
        
>    The copier here at
>    work. The user interface is great.  I can even clear jams without
>    refering to the documention.  The front panel displays the jam
>    area, the stickers inside the machine tell me what to do.  
        
        To further analize the copier:  The copier has documentation,
        its just that the documentation on clearing jams is written next
        to the places that need to be cleared.  The information the user
        needs is right next to where it is needed.  If the user needs
        help he doesn't have to go searching for it, and if the user
        doesn't need help it isn't in the way.
        
        					B.J.

Concerning documentation, copiers, etc:

I think the "don't need documentation for my copier" phenomenon has more to do
with "copier fluency" becoming the norm, and maybe not so much about the
level of documentation or user interface.  I'd guarantee you that if you took
"Unfrozen caveman lawyer" and stuck him in front of the copier, he'd be a bit
frightened and confused.

I remember about 16 years ago when ATMs first started happening, most people who
encountered them just flat didn't/couldn't understand how to use them.  Even when
the machine sat there, flashing instructions over and over, they'd just throw
their hands up in despair, complaining about stupid computers that don't make
any sense.

Well, flash forward 16 years, and I can still find some ATMs that are the same
make/model as a few I saw as early as 14 years ago (when people were still
solidly confused by them), and while their UI have improved in some small ways
(better defaulting, assumed decimal point, etc), they're substantially the same
machine with pretty much the same UI as existed years ago.

What changed?  People got ATM literate.  Now, the average person is no more
frightened of operating an ATM than they are frightened of driving their car in
Boston.  (Ok, maybe that just contradicted my point.)

I'd say that computer documentation will get more sparse when people are more
computer literate, and that will be more a reflection of current levels of
computer literacy than it will be a reflection of the state of the art of 
computer documentation.

    
    The idea of no documentation really only means no traditional paper
    documentation.  A product that by the way is designed makes its use
    intuitive simply has the documentation designed into it.  There is
    ALWAYS documentation.  It is simply a matter of how/where you provide
    it.
    
    Steve
    

	re .43:

>I'd say that computer documentation will get more sparse when people are more
>computer literate, and that will be more a reflection of current levels of
>computer literacy than it will be a reflection of the state of the art of 
>computer documentation.

	Well, I'm fairly computer literate. And that has got nothing
	whatever to do with the fact that I still need to plough through
	reams of documentation even to install DECwrite, let alone use it.

	A few weeks ago, I installed DECwrite V2.0, and realised I really
	wanted British English (although when writing for an American
	audience I sometimes spell check "American" as a courtesy). But
	it was so much hassle I just took the easy way out and installed
	the default - American English. Well, now I need a British English
	spell check, so I have to haul all 94,000 blocks across the network
	again, and install it with the *right* parameters fro British
	English... and before I do that I have to wade through the Release
	Notes and the Installation Guide, which takes a whole morning.

	How "computer literate" I am (actually, I know VMS fairly well)
	is nothing at all to do with it. Evidence: if I go the the DECwrite
	notesfile and complain of a problem, there will be an instant
	chorus of "Did you read the Release Notes? Did you follow all
	the instructions in the Installation Guide?"

	One day, product teams will realise that users out there

	(a) use more than one product (theirs), and also

	(b) have other (better) things to do than play with product manuals.

	Software should be there, and when needed it should be invoked,
	used and dismissed. It should *not* set the user a reading syllabus
	similar to an undergraduate course.

	/Tom

    I think the size of computer manuals is often a reflection of not the
    state of computer literacy, or the state of computer documentation, but
    the state of computers and particularly computer software.
    
    It's also important to tell the users what they need to know, but not
    more.  Kathy's copier example is a good one.  It does come with
    documentation, embossed on the sides and top.  As soon as you try to
    use one of the more advanced features, you run into problems.
    
    More to the point, have you seen the *repair* manuals for copiers? 
    They are doubtless substantial.

    Users (internal and external) do read and _use_ documentation.  That is
    a fact.  Some software works better than others and the same is true
    for documentation.
    
    The key to producing useful documentation is to talk with real or
    simulated users about how they will _use_ the software product.  The
    documentation development cycle should begin with interviewing the
    users and end with testing by the users.  This is the goal and the
    challenge here at DEC.
    
    -jay keddie, writer/consultant, Information Design and
    Consulting/Merrimack

    Very interesting topics being discussed in this notesfile!
    
    After 5 1/2 years here at DEC and at least one dozen software
    documentation projects (conceptual, procedural, and referential-type
    guides) at 10 different engineering groups and sites all over New
    England, here is my advice to engineers who work with writers and
    writers who work with engineers and those who manage both:
    
    - Value each other's work (it is difficult, disciplined work -- honor
    that contribution)
    
    - Set expectations and boundaries (both engineers and writers should
    talk with users, engineers produce functionality, and writers
    document that functionality in a variety of ways)...some of the more
    important expectations are (from a writer's point of view):
    
      - engineers need to share their time and knowledge with writers (both 
        are traveling up steep learning curves and this has to be
        recognized and scheduled in (time-wise))
    
      - engineers [and users] need to review documentation to provide 
        feedback to the writer on the scope, content, and accuracy of the 
        technical information (writers also need to teach engineers how to 
        review technical material)
    
      - engineering management _must_ schedule documentation review time 
        into engineering development cycle schedules (if they do not, they 
        risk a poorly documented product and a stressful engineer/writer 
        relationship)
    
    - develop cross-functional skills (writers should teach engineers how
    to improve their communication skills [this is gonna get me into a lot 
    of trouble] both written and oral and engineers should teach writers
    how to improve their technical skills such as analysis and design,
    testing, and using relevant tools)
    
    - listen to each other, communicate with each other, challenge each
    other's ideas and perspectives, plan collaborative work activites with
    each other, and endlessly provide each other with feedback on how the
    documentation process [the key] is going...this all leads to improving
    the product/information development cycle...I firmly believe that the
    key to producing more useful technical documentation lies in
    _improving_ [constantly improving] the information product development 
    cycle, not simply insisting that all technical writers have advanced 
    computer science degrees  
    
    - keeping the focus on the _user_ (we should now be beyond the stage of
    "engineering for engineering sake" and "documentation for documentation
    sake"...and well grounded into making all engineering tasks and
    documentation tasks count and add value to the user's work)
    
    That is about it for now (the remaining material will be in my book
    "The Complete Technical Writer" which is due to be published in 2001)
    
    -jay keddie, writer/consultant, IDC/MKO

    To continue along the lines of .48 - Let me relate what our 
    software development group has done. We are a smaller
    group, about 30 developers. We work with 5-7 writers.

    Until a while ago, I think it was fair to say that most of us
    in engineering had little respect for our documentation counterparts.
    I can't speak for the other developers, but I think my poor
    opinion was caused because I was spoiled in my early years
    at DEC. When I first joined the company, I worked with an
    outstanding writer. His contributions to the project extended 
    well beyond documentation. For example he had more input
    on product decisions than most developers ( Yea - I'm
    talking about you John P. - I know you read this conference).
    I thought all writers were like this, and was disappointed
    when other writers did not live up to my (falsely set) expectations.

    In any case, several people recognized that we were having
    problems creating documentation. As a result, I created a team.
    Our goal was simple: Improve the way we produce documentation.
    I asked for volunteers from development, documentation, and management.
    The response I received was overwhelming. We put together a
    team which consisted of 5 writers, 5 developers, a documentation
    supervisor, and a development supervisor.

    While the team has only been in place a few months, and we meet
    as a team for only an hour or two every three weeks (although
    smaller working groups meet a little more frequently) I think
    it has worked out great.

    Although we are just finishing our first proposals for change
    (dealing with the way we make sure documentation examples
    are verified and tested, and improving the way we produce
    release notes), I feel we have made significant improvement
    in the relationship between the groups. Just working together,
    understanding problems from both sides, and *listening* to each
    other, has given us a much better understanding of how each group
    works.

    Again, we are still early in our work. I'm afraid I can not
    point to significant improvements in our documentation (yet?).
    However, even if we were to quit now, and produced nothing,
    I think the time we spent, just working with each other, has
    paid off in improved relations.

    I would suggest that other groups might consider such an idea.
    I've talked long enough. If anyone is interested in more
    details of our department's efforts, please send me mail.

    				Thank you for listening,

    				Ed
    

    
    .48 says that engineers should teach writers how to be more technical.
    
    .49 was "spoiled" early on by a writer who (I assume) was very
    technical.
    
    I guess I was "spoiled" in the same manner, by different writers.
    
    Are writers less technical today than they were n years ago? Is this a
    cause for strained relationskips between engineers and writers?
    

    A better question might be: Are both engineers and writers with the
    onslaught of _system integration_ becoming more focused in their
    expertise and less familiar with the "big picture"?
    
    I think that writers 7-8 years ago had less to deal [technically] than
    writers today who have to document new operating systems, multiplatform
    applications, and integrated technologies.  From my experience, I have
    found there is a wide range of technical expertise amongst programmers
    and software engineers in the areas of distributed computing, object
    oriented programming, and other newer engineering techniques.
    
    I think that engineers should see that both writers and engineers are
    climbing up this steep learning curve that the computer industry is
    producing for us [or rather I should say that our _customers_ are
    asking of us].
    
    We need teams of engineers, writers, human factors specialists, graphic
    artists, editors, and customer representatives to keep pace with the
    new product development cycles and that will share information and
    expertise amongst its members.
    
    -jay keddie
     

    
    Actually, I'm more interested in the tighter question: over the years,
    have technical writers at DEC become more or less proficient with
    regard to the products about which they write, and how has this affected
    their working relationship with engineers (or, if you like, what effect
    has this had on the "virtual team")?
    

    Good question.
    
    I think that one of the problems here at DEC is that we shuffle writers
    around too much without letting them become fully grounded in the base
    technologies that they spend their working lives documenting.
    
    I also think that this _void_ (if you will) causes engineers to spend
    more and more of their time explaining basic concepts to writers and
    ultimately leads to documentation that is not a deep as it might need
    to be for the target audience.
    
    This could be a side effect of virtual teams.

	And, while I'm second to none in realising the importance of
	technical understanding in writers, there's a Catch-22:
	somebody needs to be involved *from the start* in writing
	manuals who is thoroughly IGNORANT of the product!

	As writers get more familiar with the product, their ability
	to put themselves in the place of an unsophisticated user
	becomes more and more limited. hence the many Digital products
	I have used which have counter-intuitive features, and blank
	spots in the documentation corresponding to those features!
	I assume this means both engineers and writers assumed that
	it was so obvious how these features were used that it didn't
	rate a mention.

	The worst case is that you start the product, find yourself
	looking at a window with various menus, but can't get anything
	to happen. Eventually, within DEC, you try looking in Notes, and
	find... "Oh, you haven't created a library! You have to do that
	first!" or "You have to select all the text before you can change
	language"...

	Users out there are demanding products that are easier and easier
	to use. They aren't patient at all. We need to combine expertise
	and naivete in the way we write manuals.

	/Tom

    re .-1
    
    Whilst I agree that one should not lose sight of the beginner's
    viewpoint, I think your reasoning isn't valid.  To teach (and that's
    what writing documentation is) means you need to know as much
    as possible about the subject you're teaching.  Only then
    can you understand all ways in which you might present the
    material, and select the best way for your audience.

    I've found a solution for the problem: have writers who know the
    product throughly, and have _reviewers_ who are beginners, and must learn
    the product from scratch using only the documentation.  When I was
    working on EDT the manual was written by a very knowledgeable, highly
    skilled writer.  One of the reviewers was my 8-year-old daughter, who
    had never seen the product before, and wasn't even very familiar with
    terminals.  My daughter tried all of the examples, for example, from a
    background completely uncluttered by knowledge of what the product
    would do.
    
    As a side effect, my daughter is proud of having contributed to the
    success of this product, and she is now using it at her university.
        John Sauter

    Documentation is as much a part of the product as the executables and
    as such it must be tested, just as the executables are (and maybe in
    coordination).  Any sw product that doesn't include documentation
    testing isn't up to our standards.

	re .56:

>    I've found a solution for the problem: have writers who know the
>    product throughly, and have _reviewers_ who are beginners, and must learn
>    the product from scratch using only the documentation.  When I was
>    working on EDT the manual was written by a very knowledgeable, highly
>    skilled writer.  One of the reviewers was my 8-year-old daughter, who
>    had never seen the product before, and wasn't even very familiar with
>    terminals.  My daughter tried all of the examples, for example, from a
>    background completely uncluttered by knowledge of what the product
>    would do.

	That's exactly what I meant!

	/Tom