> Mozilla is an extremely large and complex application with a high barrier
> to entry for new engineers (particularly those outside Netscape.) Having
> each engineer spending a week doing a brain dump of stuff they know about
> their area would go a long way towards lowering that barrier, and
> increasing everyone's productivity.
>
The importance of providing written designs and documentation early in the
process of development, is, in my opinion, very real.
I recently read somewhere that software engineering can be viewed as largely
a matter of writing descriptions. Think about all of the things that are
important to us as developers; computer languages, which are used to describe
the system in a way that the computer can understand; patterns and object
oriented architectures, which help us organize these descriptions in ways
that are more meaningful and easy to understand. There are product
requirements, which help to relate the machine we are describing to the
end-user domain, and there are books an manuals that help users relate the
machine we provide to their day to day needs. Yet, still, this is not enough
-- there has to be descriptions that are above the code, but below the
interest of the end user, that help us to understand the source, to
understand the machine we have built, both on a global sense -- in terms of
how all of the pieces fit together, and in the less global sense -- in order
to help us understand what each component is, how it operates, and what
interfaces it provides.
Think for a moment about the following scenario -- you are asked to work on a
bug that involves libimg, events, or layout, or any other of a number of
things. You are being asked to look at this because the people who have all
of this knowledge in their heads have left the company, or are on sabbatical.
Where do you turn to? As you work, what assumptions have you made about the
architecture that are false, and might lead to an introduction of bugs?
Or, consider you are a engineer who wants to contribute some software to
mozilla. Some components are rather well documented, others have
documentation that is old and invalid, and numerous others have yet to be
described. Where do you start?
I personally think the best thing that can be done by mozilla.org at this
point is to establish a minimum standard towards deriving a readable,
understandable description of the mozilla machine at both the macro and the
global level. What mozilla.org maintains is intellectual property. The less
understood the intellectual property of mozilla.org is, the less useful it
is, and the more likely mistakes will be made that affect stability,
performance, and usability.
I think a useful addition to the policies of mozilla.org would be the
insistence that a certain standard be met by contributors regarding how the
systems they are submitting to the source tree are described. If it is
important enough to be checked in, it is important enough to be be described
in such a way that maximizes its benefit to the community of developers who
must work with it. Those of you who see this as more work, consider the
following:
-- there are parts of the systems you are building that are not adequately
described by code alone. "Just read the code" is a poor excuse.
-- the few hours it takes you to provide a description will no doubt save
others many more hours in trying to come up with the same understanding of
the component you had at the time the component was being created or
modified. It will also reduce the likelihood that your view of the system
will be distorted in some way.
I call on mozilla.org, as it tries to prioritize the issues that it must
address in the future, to consider the need to preserve and document the
knowledge investment we have but only begun to adequately describe, and to
put in place the mechanisms by which contributions span not only code, but
the written information needed to make sure that code is well understood and
useable by anyone who cares to learn. I also call on mozilla.org to try and
derive some simple, effective, and, as much as possible non-intrusive means
by which this information can be gathered, and for mozilla.org to recognize
its importance and to enfore the policies that they put in place much the way
they enfore the requirement that code be reviewed and super-reviewed before
being checked in.
Thanks for listening,
syd
>
> Let the discussion begin :-)
>
> Gerv
