I don't wish to overcomplicate, but do you want some grouping of features... (e.g. a parentFeature tag) if we're looking at the same sort of granularity as unit tests, that should be quite fine... but many of them may be aspects of the same "feature"...
-- Rob 2010/1/6 Rafael Schloming <rafa...@redhat.com> > Alan Conway wrote: > >> On 01/06/2010 06:52 AM, Robert Godfrey wrote: >> >>> 2010/1/6 Rafael Schloming<rafa...@redhat.com> >>> >>> Robert Godfrey wrote: >>>> >>>> Overall I think with a bit of work from both the C++ and Java >>>>> communities >>>>> we >>>>> can get the brokers to look and behave much more similarly... however >>>>> we >>>>> will also need to change the way we work a bit so that when we decide >>>>> to >>>>> add >>>>> new features we attempt to discuss and agree before implementing. It >>>>> will >>>>> do >>>>> no good to get the brokers temporarily aligned if they immediately >>>>> begin >>>>> to >>>>> drift apart again. >>>>> >>>>> >>>> I'm just thinking aloud here, but perhaps it would help to gather our >>>> various disparate documentation snippits into a single canonical feature >>>> glossary somewhere in SVN. Ideally in some format that could be easily >>>> fed >>>> into the documentation, but could also serve as a source for other >>>> things >>>> such as generating test matrices, and doing feature based coverage >>>> analysis. >>>> >>>> --Rafael >>>> >>>> >>>> >>>> That sounds like an excellent idea... >>> >>> >> Can jrobie's proposed docbook for documentation project provide the right >> format for this? It's XML so should be possible to generate various types of >> file. Seems like something we want to be able to inject into the user doc as >> well. >> > > Possibly, I'm not a docbook expert. Either way I suspect a simple XML file > could be trivially transformed into docbook and whatever else we need, e.g. > something along the lines of: > > <feature name="foo" title="Foo"> > <description> > Blah blah blah. > </description> > > <component name="java-broker"/> > <component name="cpp-broker"/> > > <test ref="pointer-to-test"/> > ... > </feature> > > I'm not sure the extent to which we want to cross reference > tests/components/etc against this sort of thing. If that's something we feel > would be valuable then I suspect making up a simple XML format and > translating to docbook would be the way to go. If on the other hand it's > essentially just a documentation-only feature glossary then I'm sure docbook > alone would be sufficient. > > As long as the format is fairly regular, I'm not particularly fussed either > way as it should be straightforward to translate later if necessary. > > --Rafael > > > > --------------------------------------------------------------------- > Apache Qpid - AMQP Messaging Implementation > Project: http://qpid.apache.org > Use/Interact: mailto:dev-subscr...@qpid.apache.org > >
