Re: Maybe We Need a New Job Title

["Dave Whelan" <dave -dot- whelan -at- home -dot- com>]

Tony says:
> This can occur if the code is well designed (i.e., if the developers had
an
> adequate understanding of the end-users and their goals).  But - and this
> has been my experience - if the developers really do not have an adequate
> understanding of the end-user's goals, the resulting "spaghetti" code is a
> poor input to creating effective documentation.

I see what you mean, but it's worth pointing out a significant difference
because I think this is confusing two issues: developing a successful
product and developing well designed code. Understanding user goals is
crucial in developing a successful product but is, IMO, irrelevant in
developing well designed code. Well designed code depends good software
engineering. For example, one program might contain well designed code that
is easy to follow and document but doesn't do what the user wants to do;
another program might do exactly what the user wants it to do but might have
been designed using spaghetti code and other bad habits that make it very
difficult for anyone to understand and document, including the original
programmer.

This might seem to be splitting hairs but, again IMO, this hair should be
split. Documenting product usage and documenting the code are not the same
thing. They belong in different camps, have different aims, and appear at
different times. Usage documentation belongs in the marketing domain because
it depends on users' goals; it aims to show people how to use the product;
and, ideally, it starts the project. Code documentation belongs in the
technical domain, because only techies will ever see it; it aims to make it
easy to understand the code in the future, and usually ends the project.

Regards,
Dave.

-----
David P. Whelan
Whelan Technical Services
(204) 334-1339
dave -dot- whelan -at- home -dot- com
http://members.home.net/whelantechnicalservices
-----