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 2010/04/23 17:20:59 UTC
Versioning DocBook and API docs on the Qpid Web Site
I'm getting ready to post the DocBook docs on the Qpid web site along
with API docs (looks like early next week at this point).
I want to make sure we have a good plan to handle versions and links
among documents. I think a file structure like this might work well:
Versions
http://qpid.apache.org/doc/
contains all docs
http://qpid.apache.org/devel/
symlink to the devel version of the documentation
http://qpid.apache.org/stable/
symlink to the docs for the latest release
http://qpid.apache.org/doc/ 0.6/
docs for a specific version
Subdirectories
http://qpid.apache.org/doc/stable/book/
Current Wiki, converted to book. We may eventually subdivide this into
different guides, e.g.
http://qpid.apache.org/doc/stable/book/programming, or
http://qpid.apache.org/doc/stable/book/broker-java.
http://qpid.apache.org/doc/stable/api/cpp
C++ API reference, generated by Doxygen
http://qpid.apache.org/doc/stable/api/cpp
Python API reference, generated by ePydoc
Links among Documents
Links should be absolute links to the current version of the
documentation. For instance, a link from
http://qpid.apache.org/doc/0.6/book/qpid-book.html to the C++ API docs
should point to http://qpid.apache.org/doc/0.6/api/cpp
Tracking changes in the text
We should endeaver to use phrases like "since 0.6" to identify new
features and changes, so the latest documentation shows what has changed.
Does this makes sense? Once we start using a given structure, it becomes
harder to change, so I want to get agreement on this up front.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Versioning DocBook and API docs on the Qpid Web Site
Posted by Rajith Attapattu <ra...@gmail.com>.
On Fri, Apr 23, 2010 at 11:50 AM, Jonathan Robie
<jo...@redhat.com> wrote:
> If we want to post our current docs as work-in-progress, but still have the
> flexibility to be able to keep multiple versions on the site, we could put
> all docs in ./devel for now. Would you be OK with that?
For now we can post all docs under /devel or /trunk (I think that
gives the users the impression that it's work-in-progress)
(Also going forward we can continue to maintain the /devel for people
who use trunk)
Then for each release we put them under the release number.
In our website we could have links for the last 3 releases and the
rest under "Archive".
(I described this in the prototype for the website. But I can't seem
to access my apache space now)
> I like the idea of putting a header on the Wiki page. I think it should
> mention that we are "in the process of" replacing the Wiki, and link to the
> new DocBook docs.
>
> I also like the idea of not deleting the old Wiki info.
>
> Make sense?
agreed.
> Jonathan
>
> On 04/23/2010 11:34 AM, Rajith Attapattu wrote:
>>
>> I would keep it simple for now.
>>
>> We should post the current docs as work-in-progress.
>> Then when we release 0.7 we can then have our first set of version
>> controlled docs.
>> For all previous releases we should ask them to refer to the wiki docs.
>>
>> We shouldn't delete the old wiki docs.
>> Rather in bold letters we should put at the top saying that these docs
>> are deprecated and *may* only be relevant for versions< 0.7 or
>> something to that extent :)
>>
>> How does that sound?
>>
>> Rajith
>>
>> On Fri, Apr 23, 2010 at 11:20 AM, Jonathan Robie
>> <jo...@redhat.com> wrote:
>>
>>>
>>> I'm getting ready to post the DocBook docs on the Qpid web site along
>>> with
>>> API docs (looks like early next week at this point).
>>>
>>> I want to make sure we have a good plan to handle versions and links
>>> among
>>> documents. I think a file structure like this might work well:
>>>
>>> Versions
>>>
>>> http://qpid.apache.org/doc/
>>> contains all docs
>>>
>>> http://qpid.apache.org/devel/
>>> symlink to the devel version of the documentation
>>>
>>> http://qpid.apache.org/stable/
>>> symlink to the docs for the latest release
>>>
>>> http://qpid.apache.org/doc/ 0.6/
>>> docs for a specific version
>>>
>>> Subdirectories
>>>
>>> http://qpid.apache.org/doc/stable/book/
>>> Current Wiki, converted to book. We may eventually subdivide this into
>>> different guides, e.g.
>>> http://qpid.apache.org/doc/stable/book/programming,
>>> or http://qpid.apache.org/doc/stable/book/broker-java.
>>>
>>> http://qpid.apache.org/doc/stable/api/cpp
>>> C++ API reference, generated by Doxygen
>>>
>>> http://qpid.apache.org/doc/stable/api/cpp
>>> Python API reference, generated by ePydoc
>>>
>>> Links among Documents
>>>
>>> Links should be absolute links to the current version of the
>>> documentation.
>>> For instance, a link from
>>> http://qpid.apache.org/doc/0.6/book/qpid-book.html to the C++ API docs
>>> should point to http://qpid.apache.org/doc/0.6/api/cpp
>>>
>>> Tracking changes in the text
>>>
>>> We should endeaver to use phrases like "since 0.6" to identify new
>>> features
>>> and changes, so the latest documentation shows what has changed.
>>>
>>>
>>> Does this makes sense? Once we start using a given structure, it becomes
>>> harder to change, so I want to get agreement on this up front.
>>>
>>> Jonathan
>>>
>>> ---------------------------------------------------------------------
>>> 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: Versioning DocBook and API docs on the Qpid Web Site
Posted by Marnie McCormack <ma...@googlemail.com>.
Hi, sounds like a plan to me !
Thanks,
Marnie
On Fri, Apr 23, 2010 at 4:50 PM, Jonathan Robie
<jo...@redhat.com>wrote:
> If we want to post our current docs as work-in-progress, but still have the
> flexibility to be able to keep multiple versions on the site, we could put
> all docs in ./devel for now. Would you be OK with that?
>
> I like the idea of putting a header on the Wiki page. I think it should
> mention that we are "in the process of" replacing the Wiki, and link to the
> new DocBook docs.
>
> I also like the idea of not deleting the old Wiki info.
>
> Make sense?
>
> Jonathan
>
>
> On 04/23/2010 11:34 AM, Rajith Attapattu wrote:
>
>> I would keep it simple for now.
>>
>> We should post the current docs as work-in-progress.
>> Then when we release 0.7 we can then have our first set of version
>> controlled docs.
>> For all previous releases we should ask them to refer to the wiki docs.
>>
>> We shouldn't delete the old wiki docs.
>> Rather in bold letters we should put at the top saying that these docs
>> are deprecated and *may* only be relevant for versions< 0.7 or
>> something to that extent :)
>>
>> How does that sound?
>>
>> Rajith
>>
>> On Fri, Apr 23, 2010 at 11:20 AM, Jonathan Robie
>> <jo...@redhat.com> wrote:
>>
>>
>>> I'm getting ready to post the DocBook docs on the Qpid web site along
>>> with
>>> API docs (looks like early next week at this point).
>>>
>>> I want to make sure we have a good plan to handle versions and links
>>> among
>>> documents. I think a file structure like this might work well:
>>>
>>> Versions
>>>
>>> http://qpid.apache.org/doc/
>>> contains all docs
>>>
>>> http://qpid.apache.org/devel/
>>> symlink to the devel version of the documentation
>>>
>>> http://qpid.apache.org/stable/
>>> symlink to the docs for the latest release
>>>
>>> http://qpid.apache.org/doc/ 0.6/
>>> docs for a specific version
>>>
>>> Subdirectories
>>>
>>> http://qpid.apache.org/doc/stable/book/
>>> Current Wiki, converted to book. We may eventually subdivide this into
>>> different guides, e.g.
>>> http://qpid.apache.org/doc/stable/book/programming,
>>> or http://qpid.apache.org/doc/stable/book/broker-java.
>>>
>>> http://qpid.apache.org/doc/stable/api/cpp
>>> C++ API reference, generated by Doxygen
>>>
>>> http://qpid.apache.org/doc/stable/api/cpp
>>> Python API reference, generated by ePydoc
>>>
>>> Links among Documents
>>>
>>> Links should be absolute links to the current version of the
>>> documentation.
>>> For instance, a link from
>>> http://qpid.apache.org/doc/0.6/book/qpid-book.html to the C++ API docs
>>> should point to http://qpid.apache.org/doc/0.6/api/cpp
>>>
>>> Tracking changes in the text
>>>
>>> We should endeaver to use phrases like "since 0.6" to identify new
>>> features
>>> and changes, so the latest documentation shows what has changed.
>>>
>>>
>>> Does this makes sense? Once we start using a given structure, it becomes
>>> harder to change, so I want to get agreement on this up front.
>>>
>>> Jonathan
>>>
>>> ---------------------------------------------------------------------
>>> 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: Versioning DocBook and API docs on the Qpid Web Site
Posted by Jonathan Robie <jo...@redhat.com>.
If we want to post our current docs as work-in-progress, but still have
the flexibility to be able to keep multiple versions on the site, we
could put all docs in ./devel for now. Would you be OK with that?
I like the idea of putting a header on the Wiki page. I think it should
mention that we are "in the process of" replacing the Wiki, and link to
the new DocBook docs.
I also like the idea of not deleting the old Wiki info.
Make sense?
Jonathan
On 04/23/2010 11:34 AM, Rajith Attapattu wrote:
> I would keep it simple for now.
>
> We should post the current docs as work-in-progress.
> Then when we release 0.7 we can then have our first set of version
> controlled docs.
> For all previous releases we should ask them to refer to the wiki docs.
>
> We shouldn't delete the old wiki docs.
> Rather in bold letters we should put at the top saying that these docs
> are deprecated and *may* only be relevant for versions< 0.7 or
> something to that extent :)
>
> How does that sound?
>
> Rajith
>
> On Fri, Apr 23, 2010 at 11:20 AM, Jonathan Robie
> <jo...@redhat.com> wrote:
>
>> I'm getting ready to post the DocBook docs on the Qpid web site along with
>> API docs (looks like early next week at this point).
>>
>> I want to make sure we have a good plan to handle versions and links among
>> documents. I think a file structure like this might work well:
>>
>> Versions
>>
>> http://qpid.apache.org/doc/
>> contains all docs
>>
>> http://qpid.apache.org/devel/
>> symlink to the devel version of the documentation
>>
>> http://qpid.apache.org/stable/
>> symlink to the docs for the latest release
>>
>> http://qpid.apache.org/doc/ 0.6/
>> docs for a specific version
>>
>> Subdirectories
>>
>> http://qpid.apache.org/doc/stable/book/
>> Current Wiki, converted to book. We may eventually subdivide this into
>> different guides, e.g. http://qpid.apache.org/doc/stable/book/programming,
>> or http://qpid.apache.org/doc/stable/book/broker-java.
>>
>> http://qpid.apache.org/doc/stable/api/cpp
>> C++ API reference, generated by Doxygen
>>
>> http://qpid.apache.org/doc/stable/api/cpp
>> Python API reference, generated by ePydoc
>>
>> Links among Documents
>>
>> Links should be absolute links to the current version of the documentation.
>> For instance, a link from
>> http://qpid.apache.org/doc/0.6/book/qpid-book.html to the C++ API docs
>> should point to http://qpid.apache.org/doc/0.6/api/cpp
>>
>> Tracking changes in the text
>>
>> We should endeaver to use phrases like "since 0.6" to identify new features
>> and changes, so the latest documentation shows what has changed.
>>
>>
>> Does this makes sense? Once we start using a given structure, it becomes
>> harder to change, so I want to get agreement on this up front.
>>
>> Jonathan
>>
>> ---------------------------------------------------------------------
>> 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: Versioning DocBook and API docs on the Qpid Web Site
Posted by Rajith Attapattu <ra...@gmail.com>.
I would keep it simple for now.
We should post the current docs as work-in-progress.
Then when we release 0.7 we can then have our first set of version
controlled docs.
For all previous releases we should ask them to refer to the wiki docs.
We shouldn't delete the old wiki docs.
Rather in bold letters we should put at the top saying that these docs
are deprecated and *may* only be relevant for versions < 0.7 or
something to that extent :)
How does that sound?
Rajith
On Fri, Apr 23, 2010 at 11:20 AM, Jonathan Robie
<jo...@redhat.com> wrote:
> I'm getting ready to post the DocBook docs on the Qpid web site along with
> API docs (looks like early next week at this point).
>
> I want to make sure we have a good plan to handle versions and links among
> documents. I think a file structure like this might work well:
>
> Versions
>
> http://qpid.apache.org/doc/
> contains all docs
>
> http://qpid.apache.org/devel/
> symlink to the devel version of the documentation
>
> http://qpid.apache.org/stable/
> symlink to the docs for the latest release
>
> http://qpid.apache.org/doc/ 0.6/
> docs for a specific version
>
> Subdirectories
>
> http://qpid.apache.org/doc/stable/book/
> Current Wiki, converted to book. We may eventually subdivide this into
> different guides, e.g. http://qpid.apache.org/doc/stable/book/programming,
> or http://qpid.apache.org/doc/stable/book/broker-java.
>
> http://qpid.apache.org/doc/stable/api/cpp
> C++ API reference, generated by Doxygen
>
> http://qpid.apache.org/doc/stable/api/cpp
> Python API reference, generated by ePydoc
>
> Links among Documents
>
> Links should be absolute links to the current version of the documentation.
> For instance, a link from
> http://qpid.apache.org/doc/0.6/book/qpid-book.html to the C++ API docs
> should point to http://qpid.apache.org/doc/0.6/api/cpp
>
> Tracking changes in the text
>
> We should endeaver to use phrases like "since 0.6" to identify new features
> and changes, so the latest documentation shows what has changed.
>
>
> Does this makes sense? Once we start using a given structure, it becomes
> harder to change, so I want to get agreement on this up front.
>
> 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
Re: Versioning DocBook and API docs on the Qpid Web Site
Posted by Jonathan Robie <jo...@redhat.com>.
Hi Marnie,
I think ./devel always refers to whatever matches what the most recent
docs in svn, ./stable always refers to the latest released docs (which
will have even numbers), and we only create ./0.6, ./0.8, etc. when we
do a release. So you're right, we won't see odd version numbers here.
Does that make sense?
Jonathan
On 04/23/2010 11:28 AM, Marnie McCormack wrote:
> Hi Jonathan,
>
> I missed the debate about versions, but we'll only ref 0.6 then 0.8 in doc
> is that right ? So if we're working on something with a 0.7 version on trunk
> when its released the docs should ref 0.8 but the devel links will go to 0.7
> docs ?
>
> Sorry if I have the stick by the wrong end (not that the numbers are
> confusing :-)
>
> I think whats you're proposing makes sense, though I'm not sure how best to
> ref back and forward as we make changes but using absolute refs avoids
> confusion or inadvertant links to non-relevant pages.
>
> Thanks,
> Marnie
>
> On Fri, Apr 23, 2010 at 4:20 PM, Jonathan Robie
> <jo...@redhat.com>wrote:
>
>
>> I'm getting ready to post the DocBook docs on the Qpid web site along with
>> API docs (looks like early next week at this point).
>>
>> I want to make sure we have a good plan to handle versions and links among
>> documents. I think a file structure like this might work well:
>>
>> Versions
>>
>> http://qpid.apache.org/doc/
>> contains all docs
>>
>> http://qpid.apache.org/devel/
>> symlink to the devel version of the documentation
>>
>> http://qpid.apache.org/stable/
>> symlink to the docs for the latest release
>>
>> http://qpid.apache.org/doc/ 0.6/
>> docs for a specific version
>>
>> Subdirectories
>>
>> http://qpid.apache.org/doc/stable/book/
>> Current Wiki, converted to book. We may eventually subdivide this into
>> different guides, e.g. http://qpid.apache.org/doc/stable/book/programming,
>> or http://qpid.apache.org/doc/stable/book/broker-java.
>>
>> http://qpid.apache.org/doc/stable/api/cpp
>> C++ API reference, generated by Doxygen
>>
>> http://qpid.apache.org/doc/stable/api/cpp
>> Python API reference, generated by ePydoc
>>
>> Links among Documents
>>
>> Links should be absolute links to the current version of the documentation.
>> For instance, a link from
>> http://qpid.apache.org/doc/0.6/book/qpid-book.html to the C++ API docs
>> should point to http://qpid.apache.org/doc/0.6/api/cpp
>>
>> Tracking changes in the text
>>
>> We should endeaver to use phrases like "since 0.6" to identify new features
>> and changes, so the latest documentation shows what has changed.
>>
>>
>> Does this makes sense? Once we start using a given structure, it becomes
>> harder to change, so I want to get agreement on this up front.
>>
>> Jonathan
>>
>> ---------------------------------------------------------------------
>> 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: Versioning DocBook and API docs on the Qpid Web Site
Posted by Marnie McCormack <ma...@googlemail.com>.
Hi Jonathan,
I missed the debate about versions, but we'll only ref 0.6 then 0.8 in doc
is that right ? So if we're working on something with a 0.7 version on trunk
when its released the docs should ref 0.8 but the devel links will go to 0.7
docs ?
Sorry if I have the stick by the wrong end (not that the numbers are
confusing :-)
I think whats you're proposing makes sense, though I'm not sure how best to
ref back and forward as we make changes but using absolute refs avoids
confusion or inadvertant links to non-relevant pages.
Thanks,
Marnie
On Fri, Apr 23, 2010 at 4:20 PM, Jonathan Robie
<jo...@redhat.com>wrote:
> I'm getting ready to post the DocBook docs on the Qpid web site along with
> API docs (looks like early next week at this point).
>
> I want to make sure we have a good plan to handle versions and links among
> documents. I think a file structure like this might work well:
>
> Versions
>
> http://qpid.apache.org/doc/
> contains all docs
>
> http://qpid.apache.org/devel/
> symlink to the devel version of the documentation
>
> http://qpid.apache.org/stable/
> symlink to the docs for the latest release
>
> http://qpid.apache.org/doc/ 0.6/
> docs for a specific version
>
> Subdirectories
>
> http://qpid.apache.org/doc/stable/book/
> Current Wiki, converted to book. We may eventually subdivide this into
> different guides, e.g. http://qpid.apache.org/doc/stable/book/programming,
> or http://qpid.apache.org/doc/stable/book/broker-java.
>
> http://qpid.apache.org/doc/stable/api/cpp
> C++ API reference, generated by Doxygen
>
> http://qpid.apache.org/doc/stable/api/cpp
> Python API reference, generated by ePydoc
>
> Links among Documents
>
> Links should be absolute links to the current version of the documentation.
> For instance, a link from
> http://qpid.apache.org/doc/0.6/book/qpid-book.html to the C++ API docs
> should point to http://qpid.apache.org/doc/0.6/api/cpp
>
> Tracking changes in the text
>
> We should endeaver to use phrases like "since 0.6" to identify new features
> and changes, so the latest documentation shows what has changed.
>
>
> Does this makes sense? Once we start using a given structure, it becomes
> harder to change, so I want to get agreement on this up front.
>
> Jonathan
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>