You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@qpid.apache.org by Jonathan Robie <jo...@redhat.com> on 2009/12/02 21:25:13 UTC
Documentation to svn / DocBook : first steps
I'd like to start converting documentation to svn / DocBook as follows:
1. Create a DocBook document that corresponds to this page and the pages
it references:
http://qpid.apache.org/documentation.html
At least initially, this can be a single document, composed of multiple
entities. External links are referenced via URLs, Wiki content is
incorporated into the sections of this document. To enable links to
specific versions of generated API documentation, generated HTML will
also be checked in for each release, in the documentation subtree.
I will create a subdirectory under trunk for the XML source:
trunk/qpid/documentation/src
The initial check-in corresponds exactly to the current content, so that
source code control reflects the changes made to this content.
2. Enhance existing sections with existing text, where available.
In some cases, there is existing text that can be used to enhance
existing sections of the documentation. For instance, I've written some
things on federation and clustering that could be added, and there is
text in some existing vendor documentation that could probably be used
for some existing sections.
3. Improve the overall organization
This should especially focus on a few simple goals:
- Make sure the documentation shows people how to easily install,
configure, and run the brokers, in an obvious place
- Make sure the documentation shows people how to easily run the
examples, in an obvious place
4. Add missing material, improve existing sections with new work.
I think steps 1-3 can be done by mostly one person in a week, though
it's possible that I'm being optimistic. I plan to do this next week,
but my father is gravely ill, so my time is somewhat unpredictable this
month. Rafi and Rajith have both offered to help, and I may well take
them up on that even in the first week.
Once that is done, we'll have a template that other people can easily
add to. We need to figure out how to divide up the work on this. I'll be
dividing up the document into XML entities that individuals can be
responsible for, so we can have someone primarily responsible for the
WCF, the Java broker, the new API, etc.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Documentation to svn / DocBook : first steps
Posted by Robbie Gemmell <ro...@gmail.com>.
+1 for doc
2009/12/2 Rafael Schloming <ra...@redhat.com>:
>
> Robert Godfrey wrote:
>>
>> 2009/12/2 Aidan Skinner <ai...@gmail.com>
>>
>>> On Wed, Dec 2, 2009 at 10:12 PM, Rajith Attapattu <ra...@gmail.com>
>>> wrote:
>>>
>>>> sorry for being picky, but I'd prefer if you use docs instead of
>>>> documentation as the folder name :)
>>>> trunk/qpid/documentation/src --> trunk/qpid/docs/src
>>>
>>> Could it be doc/ ? That's traditional ;)
>>>
>>>
>> +1 to doc/
>
> +1
>
> --Rafael
>
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Documentation to svn / DocBook : first steps
Posted by Rafael Schloming <ra...@redhat.com>.
Robert Godfrey wrote:
> 2009/12/2 Aidan Skinner <ai...@gmail.com>
>
>> On Wed, Dec 2, 2009 at 10:12 PM, Rajith Attapattu <ra...@gmail.com>
>> wrote:
>>
>>> sorry for being picky, but I'd prefer if you use docs instead of
>>> documentation as the folder name :)
>>> trunk/qpid/documentation/src --> trunk/qpid/docs/src
>> Could it be doc/ ? That's traditional ;)
>>
>>
> +1 to doc/
+1
--Rafael
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Documentation to svn / DocBook : first steps
Posted by Robert Godfrey <ro...@gmail.com>.
2009/12/2 Aidan Skinner <ai...@gmail.com>
> On Wed, Dec 2, 2009 at 10:12 PM, Rajith Attapattu <ra...@gmail.com>
> wrote:
>
> > sorry for being picky, but I'd prefer if you use docs instead of
> > documentation as the folder name :)
> > trunk/qpid/documentation/src --> trunk/qpid/docs/src
>
> Could it be doc/ ? That's traditional ;)
>
>
+1 to doc/
-- Rob
Re: Documentation to svn / DocBook : first steps
Posted by Aidan Skinner <ai...@gmail.com>.
On Wed, Dec 2, 2009 at 10:12 PM, Rajith Attapattu <ra...@gmail.com> wrote:
> sorry for being picky, but I'd prefer if you use docs instead of
> documentation as the folder name :)
> trunk/qpid/documentation/src --> trunk/qpid/docs/src
Could it be doc/ ? That's traditional ;)
- Aidan
--
Apache Qpid - AMQP, JMS, other messaging love http://qpid.apache.org
"A witty saying proves nothing" - Voltaire
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Documentation to svn / DocBook : first steps
Posted by Jonathan Robie <jo...@redhat.com>.
OK, doc wins. (And if we're down to spelling the directory names, I
gather there's agreement on the rest ;-> )
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Documentation to svn / DocBook : first steps
Posted by Rajith Attapattu <ra...@gmail.com>.
+1 for doc :)
On Wed, Dec 2, 2009 at 6:12 PM, Steve Huston <sh...@riverace.com> wrote:
>
>> sorry for being picky, but I'd prefer if you use docs instead of
>> documentation as the folder name :)
>> trunk/qpid/documentation/src --> trunk/qpid/docs/src
>>
>> Rajith
>
> Thanks for suggesting that... I agree (or doc, as others suggest).
>
>> On Wed, Dec 2, 2009 at 3:25 PM, Jonathan Robie
>> <jo...@redhat.com> wrote:
>> > I'd like to start converting documentation to svn / DocBook
>> as follows:
>> >
>> > 1. Create a DocBook document that corresponds to this page
>> and the pages it
>> > references:
>> >
>> > http://qpid.apache.org/documentation.html
>> >
>> > At least initially, this can be a single document, composed
>> of multiple
>> > entities. External links are referenced via URLs, Wiki content is
>> > incorporated into the sections of this document. To enable
>> links to specific
>> > versions of generated API documentation, generated HTML
>> will also be checked
>> > in for each release, in the documentation subtree.
>> >
>> > I will create a subdirectory under trunk for the XML source:
>> >
>> > trunk/qpid/documentation/src
>> >
>> > The initial check-in corresponds exactly to the current
>> content, so that
>> > source code control reflects the changes made to this content.
>> >
>> > 2. Enhance existing sections with existing text, where available.
>> >
>> > In some cases, there is existing text that can be used to
>> enhance existing
>> > sections of the documentation. For instance, I've written
>> some things on
>> > federation and clustering that could be added, and there is
>> text in some
>> > existing vendor documentation that could probably be used
>> for some existing
>> > sections.
>> >
>> > 3. Improve the overall organization
>> >
>> > This should especially focus on a few simple goals:
>> >
>> > - Make sure the documentation shows people how to easily
>> install, configure,
>> > and run the brokers, in an obvious place
>> > - Make sure the documentation shows people how to easily
>> run the examples,
>> > in an obvious place
>> >
>> > 4. Add missing material, improve existing sections with new work.
>> >
>> > I think steps 1-3 can be done by mostly one person in a
>> week, though it's
>> > possible that I'm being optimistic. I plan to do this next
>> week, but my
>> > father is gravely ill, so my time is somewhat unpredictable
>> this month. Rafi
>> > and Rajith have both offered to help, and I may well take
>> them up on that
>> > even in the first week.
>> >
>> > Once that is done, we'll have a template that other people
>> can easily add
>> > to. We need to figure out how to divide up the work on this. I'll
> be
>> > dividing up the document into XML entities that individuals can be
>> > responsible for, so we can have someone primarily
>> responsible for the WCF,
>> > the Java broker, the new API, etc.
>> >
>> > Jonathan
>> >
>> >
>>
> ---------------------------------------------------------------------
>> > Apache Qpid - AMQP Messaging Implementation
>> > Project: http://qpid.apache.org
>> > Use/Interact: mailto:dev-subscribe@qpid.apache.org
>> >
>> >
>>
>>
>>
>> --
>> Regards,
>>
>> Rajith Attapattu
>> Red Hat
>> http://rajith.2rlabs.com/
>>
>>
> ---------------------------------------------------------------------
>> Apache Qpid - AMQP Messaging Implementation
>> Project: http://qpid.apache.org
>> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>>
>>
>
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>
--
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
RE: Documentation to svn / DocBook : first steps
Posted by Steve Huston <sh...@riverace.com>.
> sorry for being picky, but I'd prefer if you use docs instead of
> documentation as the folder name :)
> trunk/qpid/documentation/src --> trunk/qpid/docs/src
>
> Rajith
Thanks for suggesting that... I agree (or doc, as others suggest).
> On Wed, Dec 2, 2009 at 3:25 PM, Jonathan Robie
> <jo...@redhat.com> wrote:
> > I'd like to start converting documentation to svn / DocBook
> as follows:
> >
> > 1. Create a DocBook document that corresponds to this page
> and the pages it
> > references:
> >
> > http://qpid.apache.org/documentation.html
> >
> > At least initially, this can be a single document, composed
> of multiple
> > entities. External links are referenced via URLs, Wiki content is
> > incorporated into the sections of this document. To enable
> links to specific
> > versions of generated API documentation, generated HTML
> will also be checked
> > in for each release, in the documentation subtree.
> >
> > I will create a subdirectory under trunk for the XML source:
> >
> > trunk/qpid/documentation/src
> >
> > The initial check-in corresponds exactly to the current
> content, so that
> > source code control reflects the changes made to this content.
> >
> > 2. Enhance existing sections with existing text, where available.
> >
> > In some cases, there is existing text that can be used to
> enhance existing
> > sections of the documentation. For instance, I've written
> some things on
> > federation and clustering that could be added, and there is
> text in some
> > existing vendor documentation that could probably be used
> for some existing
> > sections.
> >
> > 3. Improve the overall organization
> >
> > This should especially focus on a few simple goals:
> >
> > - Make sure the documentation shows people how to easily
> install, configure,
> > and run the brokers, in an obvious place
> > - Make sure the documentation shows people how to easily
> run the examples,
> > in an obvious place
> >
> > 4. Add missing material, improve existing sections with new work.
> >
> > I think steps 1-3 can be done by mostly one person in a
> week, though it's
> > possible that I'm being optimistic. I plan to do this next
> week, but my
> > father is gravely ill, so my time is somewhat unpredictable
> this month. Rafi
> > and Rajith have both offered to help, and I may well take
> them up on that
> > even in the first week.
> >
> > Once that is done, we'll have a template that other people
> can easily add
> > to. We need to figure out how to divide up the work on this. I'll
be
> > dividing up the document into XML entities that individuals can be
> > responsible for, so we can have someone primarily
> responsible for the WCF,
> > the Java broker, the new API, etc.
> >
> > Jonathan
> >
> >
>
---------------------------------------------------------------------
> > Apache Qpid - AMQP Messaging Implementation
> > Project: http://qpid.apache.org
> > Use/Interact: mailto:dev-subscribe@qpid.apache.org
> >
> >
>
>
>
> --
> Regards,
>
> Rajith Attapattu
> Red Hat
> http://rajith.2rlabs.com/
>
>
---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Documentation to svn / DocBook : first steps
Posted by Rajith Attapattu <ra...@gmail.com>.
sorry for being picky, but I'd prefer if you use docs instead of
documentation as the folder name :)
trunk/qpid/documentation/src --> trunk/qpid/docs/src
Rajith
On Wed, Dec 2, 2009 at 3:25 PM, Jonathan Robie
<jo...@redhat.com> wrote:
> I'd like to start converting documentation to svn / DocBook as follows:
>
> 1. Create a DocBook document that corresponds to this page and the pages it
> references:
>
> http://qpid.apache.org/documentation.html
>
> At least initially, this can be a single document, composed of multiple
> entities. External links are referenced via URLs, Wiki content is
> incorporated into the sections of this document. To enable links to specific
> versions of generated API documentation, generated HTML will also be checked
> in for each release, in the documentation subtree.
>
> I will create a subdirectory under trunk for the XML source:
>
> trunk/qpid/documentation/src
>
> The initial check-in corresponds exactly to the current content, so that
> source code control reflects the changes made to this content.
>
> 2. Enhance existing sections with existing text, where available.
>
> In some cases, there is existing text that can be used to enhance existing
> sections of the documentation. For instance, I've written some things on
> federation and clustering that could be added, and there is text in some
> existing vendor documentation that could probably be used for some existing
> sections.
>
> 3. Improve the overall organization
>
> This should especially focus on a few simple goals:
>
> - Make sure the documentation shows people how to easily install, configure,
> and run the brokers, in an obvious place
> - Make sure the documentation shows people how to easily run the examples,
> in an obvious place
>
> 4. Add missing material, improve existing sections with new work.
>
> I think steps 1-3 can be done by mostly one person in a week, though it's
> possible that I'm being optimistic. I plan to do this next week, but my
> father is gravely ill, so my time is somewhat unpredictable this month. Rafi
> and Rajith have both offered to help, and I may well take them up on that
> even in the first week.
>
> Once that is done, we'll have a template that other people can easily add
> to. We need to figure out how to divide up the work on this. I'll be
> dividing up the document into XML entities that individuals can be
> responsible for, so we can have someone primarily responsible for the WCF,
> the Java broker, the new API, etc.
>
> Jonathan
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>
--
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org