You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cxf.apache.org by Christian Schneider <ch...@die-schneider.net> on 2011/02/19 13:31:21 UTC
[Discuss] CXF Architecture and Architecture Documentation
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+Decisions
I hope we reach a consensus about these things as I think they are very
important.
Christian
--
----
http://www.liquid-reality.de
Re: [Discuss] CXF Architecture and Architecture Documentation
Posted by Christian Schneider <ch...@die-schneider.net>.
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
Re: [Discuss] CXF Architecture and Architecture Documentation
Posted by Daniel Kulp <dk...@apache.org>.
> "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
--
Daniel Kulp
dkulp@apache.org
http://dankulp.com/blog
Talend - http://www.talend.com
Re: [Discuss] CXF Architecture and Architecture Documentation
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi Eric,
yes this dicussion on the list is where the decisions are made. That
works well and should not be changed. What I would like to add is a kind
of summary that shows what the consensus was - of course with reference
to the original discussion. The problem with only doing this on the list
is that you have no place where you can easily find the decisions and it
sometimes is also a lot of work to read through all the posts and extract
the important information. So it is less about archiving and deciding
and more about accessability.
If there is no or not much interest by other committers in such a list
then I will just delete the page again. This only makes sense if we as a
community support it.
Christian
Am 20.02.2011 19:05, schrieb Eric Johnson:
> For many of the major decisions this sort of discussion is done on the
> mailing list and archived.
>
--
----
http://www.liquid-reality.de
Re: [Discuss] CXF Architecture and Architecture Documentation
Posted by Eric Johnson <em...@fusesource.com>.
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
<ch...@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/
Re: [Discuss] CXF Architecture and Architecture Documentation
Posted by Christian Schneider <ch...@die-schneider.net>.
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
Re: [Discuss] CXF Architecture and Architecture Documentation
Posted by Glen Mazza <gm...@talend.com>.
On 2/19/2011 8:24 AM, Christian Schneider wrote:
>
>> 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.
>>
no problem
>> 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.
OK, sounds good.
>> 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
Re: [Discuss] CXF Architecture and Architecture Documentation
Posted by Christian Schneider <ch...@die-schneider.net>.
Seems I overlooked the goals as they are almost at the bottom of the
Architecture guide. So they are not missing :-)
Christian
Am 19.02.2011 13:31, schrieb Christian Schneider:
> 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+Decisions
>
> I hope we reach a consensus about these things as I think they are
> very important.
>
> Christian
>
>
>
>
--
----
http://www.liquid-reality.de