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 Mon, 21 Feb 2011 19:55:13 GMT
Hi Dan,

I don´t think that writing good architecture documentation is very 
expensive. The key is to leverage the knowledge that is already there 
and to describe only the most important things.
But by asking you a lot the first point should be not so difficult :-)

Christian


Am 21.02.2011 18:56, schrieb Daniel Kulp:
>> "Architecture is the sum of the decisions about a project that are the
>> most expensive to change later. "
> The "decision" to not have up to date achitecture docs is one of the
> "decisions about a project that are the most expensive to change later".   :-)
>
> Not saying it shouldn't be fixed, it's just going to be expensive to fix from
> a time perspective.   :-)
>
>
>
> Dan
>
>
>
> On Saturday 19 February 2011 7:31:21 AM Christian Schneider wrote:
>> Hi All,
>>
>> I know that the theme is a big one and likely will spawn some larger
>> discussion still I think it is important to talk about it and to have a
>> common understanding.
>> When digging into some not so obvious issues I repeatedly stumble about
>> the fact that there are important things about CXF that I don´t know or
>> only have a vague clue of.
>> Another problem I often had is where to put new stuff or decide if a
>> classs is placed at a location where it should not be.
>>
>> These examples show in my opinion that we do not have a good
>> architecture documentation and no clean process to decide about
>> architecture and to document decisions. So I propose some things
>> and we see if we reach a consensus.
>>
>> The first thing is a question that always pops up and that is not so
>> easy. What is architecture?
>> I once read a nice definition that is quite open but still catches what
>> is important:
>> "Architecture is the sum of the decisions about a project that are the
>> most expensive to change later. "
>> Sorry that I am not able to point to a concret source of this. I think
>> this definition catches the important thing about architecture. It
>> should cover only those things that may later bite you.
>> So for example the decision it can be argued if the decision for a
>> logging framework is an architectural decision as we saw in Apache Camel
>> how fast they were able to switch to slf4j. So this was nothing
>> that was expensive to change. In any case I am curious what you guys
>> consider as a good definition for an architecture.
>>
>> I would like to come to a consensus about what we define as architecture
>> as a first starting point.
>>
>> The next thing is how to document our architecture. We have a good
>> starting point at
>> https://cwiki.apache.org/confluence/display/CXF20DOC/CXF+Architecture
>> but I think some important things are lacking. This page
>> describes the key structural elements and how some key elements work
>> together in CXF. That is very important and we should simply try to
>> improve it. I would also like to add our common definition of what
>> architecture is to that document.
>>
>> The first thing I would like to add are architectural goals. An
>> architecture can never be good in itself. It can only be judged against
>> the goals it tries to achieve. Here again we should only track the most
>> important goals.
>>
>> 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+Decision
>> s
>>
>> I hope we reach a consensus about these things as I think they are very
>> important.
>>
>> Christian

-- 
----
http://www.liquid-reality.de


Mime
View raw message