Am 19.02.2011 14:47, schrieb Glen Mazza:
On 2/19/2011 8:24 AM, Christian Schneider wrote:
The second thing I would like to add is a page about architectural
decisions. It should contain a short description of the process how we
do these decisions and a list of decisions in a well defined format. I
would also like
to limit the decisions to a certain number so we are sure that only
the most important decisions are tracked. I added such a page as my
proposal and we should discuss if this is ok for all. As I have no
idea how many decisions we should track I think we could simply start
and keep in mind that it should not grow too large. See
https://cwiki.apache.org/confluence/display/CXF20DOC/Architectural+Decisions
Errr, I'd be more comfortable about going in this direction if there
were any other Apache projects doing the same. We can guinea pig
ourselves here, but I'm not certain how useful this documentation
would be to ourselves or most readers. Rather, the reasons for
architectural designs I think can be more conveniently placed and
described within the architecture document (what you mention at the top).
Glen
Hi Glen,
I had also thought that architecture documentation only describes the
structure and the function of some important components like we do in
the current documentation aand some rules of course.
The problem with this aproach is that it does not document why we have
our structure.
So there always will be discussions about why we did things the way we
do and of course we don´t do it in a certain other way. Especially new
people will always ask and argue the same things.
On the other hand there will be some structures that perhaps are not
good anymore as the environment or the goals have changed. For both of
these problems it is important to document the why and to document
alternatives. The alternatives show that a decision was not done blindly
and the why explains how we chose from the alternatives.
I heard of this aproach already some time ago and several experienced
people adviced me to go this way. I must confess though that I have not
done this in a project so it might only be good in theory. That is why I
wanted to first start a discussion about it.
Christian
--
----
http://www.liquid-reality.de
