Re: Documentation seminar

[nhickman <nhickman -at- GVI -dot- NET>]

Warren,
I have had lots of experience with this cause. This is a tricky
business. I can tell you that from my experience of both giving and
witnessing seminars like this that they are rarely gain the outcome that
you desire in and of themselves. First of all, at a root level, other
departments don't get measured on good documentation and they didn't
hire you to pass judgement on them. It may work as a seminar to
documentation people alone. And yes, you may get a "good job" or an
"atta boy" or "that was very interesting." If this is how you will
define a successful outcome, and it could be, then a seminar is a good
tack.

But from the outset, it seems to be an assumption that if you just
provide them with your knowledge, "educate them" that change will
follow. In a university or even to people that are professional writers,
who admire and respond to that sort of thing, this might work. However,
if you start from the unstated assumption that you are expert educating,
wanting people from other areas to recognize how smart you are about
this issue, on some level most people won't accept it, or at least an
acceptance that translates to changed behavior when the chips are down.
They do see the knowledge of how to do good documentation as your job.
You were hired for it; they were not. It may be interesting, but it is
not their cup of tea. Likewise, if you sell the benefits of change, you
may get some nods "sure we'd all like to do good and save money," but
you still haven't gotten an active, concrete commitment or promise from
people. People will have gone to the church of good documentation, but
go on to living as they always have.

Instead of a seminar, where you are the only talking head, hold
collective meetings with a concrete purpose in mind. This approach has
translated to more change in my experience. You could start with a post
mortem of the last project. Have shared, rotated responsibilities where
different people record and moderate these meetings. You might expand it
to other interests besides documentation. Everyone could contribute what
could be done better, and this information is published without
attribution to higher management. Next, for example, you could hold
meetings on planning how you all will do the next project. What
promises, appointments, and deliverables will be given? Are you on the
timeline of other departments, do they allocate resource for review?
After each meeting, have action items, and begin to step to improvement
by the literal commitments that they make. You could forward this
information to management, so that people are measured by their ability
to fulfill their own commitments.

If you don't already, you could develop plans and specifications for
your own work. I have some models in my book "Building Windows 95 Help,"
but your own vision and requirements will dictate the particulars of
these documents in your situation. These documents are the stated
intention of doing good work. Get other departments to approve it and to
acknowledge their committments in your plans or to suggest alterations.

-- Nancy Hickman

Warren Singer wrote:
>
> After working for a few months at my new company I've noticed a general
> lack of awareness on the part of engineers as to the role and importance of
> documentation. This lack of awareness is expressed in sketchy SRS's that
> lack information, last-minute rush jobs to complete documentation tasks,
> failure to read existing documentation or devote the time necessary to
> provide feedback and lack of awareness of how to provide feedback.  In
> light of this I decided it would be of benifit both to me and the company
> to "educate" R&D and program managers by providing a forum for discussing
> documentation issues.
>
>  I'm am organizing a documentation seminar that will be presented to R&D
> and program managers. The main objective of the seminar is to raise
> awareness of the importance of documentation in the development cycle and
> the role of the documentation/technical writing department in this process.
>
> I thought of approaching this seminar by focusing on 2-3 relvant topics
> that would be of interest to R&D and would also help advance the cause of
> documentation. The one's I have in mind are:
> -  The documentation cycle - the purpose of this is to raise awareness of
> the importance of documentation in all stages of the product design.
> -  The Review Process - this concerns how review is provided to writers,
> i.e how to provide feedback.
> -  Mapping the communication network - looking at how decision making and
> product information is communicated through the various departments and
> sub-departments. The goal of this is to situate the documentation
> department within this decision-making tree and look at ways of
> streamlining the communication process and storage of information.
> Does anyone have ideas or suggestions about what to include in the seminar?
> I'm really interested in getting as much feedback as possible on this topic
> and any suggestions will be appreciated.
>
> Thanks,
>
> Warren
>
> ___________________________________
> Warren Singer
> Design and Documentation Department
> VocalTec Communications Ltd.
> Tel.:  +972-9-9707765 (direct)
> Fax:   +972-9-9561867
> Email: warren -at- vocaltec -dot- com
> ___________________________________
> Visit us at CeBIT 98'
>