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 <[email protected]> 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 [email protected] Blog http://documentingit.blogspot.com/
