Re: Moving Target - Part 2 (Databases)

[Andrew Woodhouse <awoodhou -at- MPC-UK -dot- COM>]

Emily Skarzenski <eskarzenski -at- dttus -dot- com> wrote :

>      Eric Ray wrote:
>=20
>      > I'm having a horrible time getting to the screens because
>      > the development environment database is hosed.
>      <snip>
>      > How many of you have dedicated Training/Documentation databases =
for
>      > your development projects?
>=20
>      We've had problems with this where I work, too. We need several
>      different environments: at least two for development, one for QA, =
one
>      for sales demos, one for training...
>=20
>      It took much begging and pleading to get a separate environment =
for
>      training. We don't have a separate one for doc. We usually =
piggyback
>      on one of the development environments. This usually works OK,
>      although they're frequently off-limits because the programmers =
are
>      "trying something". We muddle through this as best we can.
>=20
>      The designers usually set up data that works -- or data that =
*should*
>      work. Let's just say that we (writers & trainers) have become an
>      instrumental step in the testing process.
>=20
>      It's uncomfortable. And because the environments are so expensive
>      (hardware, software, IS assistance), we haven't found a =
comfortable
>      resolution -- yet.
>=20
>=20
>      Emily M. Skarzenski
>      Deloitte & Touche/ICS - Chadds Ford, PA
>      eskarzenski -at- dttus -dot- com

Regarding this thread - the original Documenting Moving Targets and this =
(part=20
2) one - my company (well, the one I work for) has just undergone a =
massive=20
reorganisation to rationalise development, test, documentation and =
support.

The problems we were having are precisely those that are being discussed =
on this=20
list. As I see it, specifically, these arise from:

- lack of specialist knowledge of writers leading to the distancing of =
the=20
development from documentation

- lack of involvement of writers in the design process

- lack of input into documentation from developers

These points are clearly all related.

The effects of this are that the documentation team has been =
obliterated, and I,=20
as the only tech. writer to survive, have done so by being flexible =
enough to=20
also take on a QA/support/design role.

The systems we write are highly complex and specialised network =
management=20
systems and the documentation we were producing did not address the =
*real*=20
issues and concerns of a knowledgable user base.

My point is essentially that if complex systems are to be effectively=20
documented, writers *must* be integral to the design process - and that =
means=20
both knowing the field to a considerable degree, and documenting the =
system in=20
*parallel* to the development.

It's simply not enough to expect to be given a product to document, and =
then=20
complaining when this product changes. The very nature of software =
development=20
precludes this idealistic view.

Anyone care to comment, or take issue, with any of this?

Regards
Andrew

-------------------------------------
Andrew Woodhouse

technical writer/QA/software test engineer/
customer support engineer/what else?

US WEST International Systems Group
Borehamwood
UK

email: awoodhou -at- isysg -dot- com
Tel: +44 181 214 3499
Fax: +44 181 214 2335
-------------------------------------=20