qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marnie McCormack <marnie.mccorm...@googlemail.com>
Subject Re: Versioning DocBook and API docs on the Qpid Web Site
Date Fri, 23 Apr 2010 15:51:21 GMT
Hi, sounds like a plan to me !

Thanks,
Marnie

On Fri, Apr 23, 2010 at 4:50 PM, Jonathan Robie
<jonathan.robie@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
>> <jonathan.robie@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
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message