cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Schneider <ch...@die-schneider.net>
Subject Re: [Discuss] CXF Architecture and Architecture Documentation
Date Sat, 19 Feb 2011 15:58:45 GMT


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


Mime
View raw message