cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Eric Johnson <emjohn...@fusesource.com>
Subject Re: [Discuss] CXF Architecture and Architecture Documentation
Date Sun, 20 Feb 2011 18:05:06 GMT
For many of the major decisions this sort of discussion is done on the
mailing list and archived.

On Saturday, February 19, 2011, Christian Schneider
<chris@die-schneider.net> wrote:
>
>
> 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
>
>

-- 
Principle Technical Writer

Phone (781) 280-4174
Skype finnmccumial
E-Mail emjohnson@fusesource.com
Blog http://documentingit.blogspot.com/

Mime
View raw message