Ruven,
I'm a man with a hammer, so I'm interested in finding out whether
your problem might be a nail...
From the issue you've described ("it's difficult to know where to
start and what to read"), it sounds like the shortage is not in the
detailed documentation per se, but in an introductory guide to the
purpose and parts of the system -- a textbook for working with the
system.
The hammer that I have is a better system for authors and students to
collaboratively write textbooks. Someone who used to work with SAP
recently suggested to me that because of the particular way it works,
the textbook system could be very useful to programmers and
configurers for large systems. (Who often find the documentation
written by the experts to be too detailed and low-level to navigate
effectively.)
Anyway, I'm interested in finding out how well the technology fits
into that of market (if at all), so I'd love to hear more about the
issues you and your team are facing, if you're willing to chat more
about it.
best regards,
Will Billingsley
Research Associate,
Centre for Applied Research in Educational Technology,
Cambridge University
On 6 Nov 2007, at 16:56, Ruven E Brooks wrote:
[EMAIL PROTECTED] wrote on 11/06/2007 10:21:14 AM:
> Who will be the reader of these documents?
>
> If the readers are going to be software developers working on
> the source do you think the exercise will be cost effective?
> After all, if there are only going to be a few readers and they
> are only going to read parts of the source (ie, on an as needed
> basis) then you documenting all of it may be more costly.
It takes a minimum of six months and, more typically, a year, before
developers joining this project have positive productivity, e.g. the
value of their efforts exceeds the cost in other people's time to
bring
them up to speed. From informal discussions, this length of time is
typical, or, perhaps, on the speedy side for applications of this
size.
If you assume that four or five developers on the team are being
replaced per year,
and that better information could cut the one year learning time
down to six months, then
we have something like 2.5 person years, every year, to invest in
getting and updating
the information.
The problems with just reading parts of the source, which is what
happens now,
are that it's often difficult to know where to start and what to
read. A large part
of the 6-12 month learning period is spend building up enough of
understand of the overall
structure so that know where to focus detailed understanding.
Ruven
