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
