qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Ritchie <ritch...@apache.org>
Subject Re: Qpid docs - file structure and organization
Date Wed, 14 Apr 2010 15:48:48 GMT
On 14 April 2010 15:24, Rajith Attapattu <rajith77@gmail.com> wrote:
> As I have mentioned in the past, we should just publish what we have right now.
> If we wait until it's perfect this will never be done.
> I am not worried about dangling links. We could resolve them in time.
>
> What we have now can't be any worse than the current wiki docs.
> **So please lets publish what we have now.**
> Once it's  more visible more people will participate.

+1, let's get an the export of docbook from svn to web automated.

Can some one with a more permissive firewall sort this out?

> Regards,
>
> Rajith



> On Wed, Apr 14, 2010 at 9:31 AM, Jonathan Robie
> <jonathan.robie@redhat.com> wrote:
>> On 04/14/2010 07:11 AM, Martin Ritchie wrote:
>>>
>>> On 16 March 2010 23:19, Rajith Attapattu<rajith77@gmail.com>  wrote:
>>>
>>>>
>>>> On Tue, Mar 16, 2010 at 6:12 PM, Robbie Gemmell
>>>> <robbie.gemmell@gmail.com>  wrote:
>>>>
>>>>>
>>>>> There were suggestions some months ago around having the website become
>>>>> a
>>>>> combination of static main pages and generated user doc pages/pdf coming
>>>>> from the DocBook source, with the wiki hanging off to the side for
>>>>> development work. Is that still the end game?
>>>>>
>>>>
>>>> Yes it is. After the prototype I did last time, a lot of folks said
>>>> they would like "blue" instead of "brown" :)
>>>> I will try to do it this weekend and post another prototype. Hopefully
>>>> people will like it !
>>>>
>>>
>>> I think we are in danger of losing some work here. If we don't make
>>> the change soon then we will have docs in svn that users can't easily
>>> access and docs on the wiki that potentially will get lost when the
>>> migration occurs.
>>>
>>> It would be great if we could have a time line for replacing the wiki
>>> page with an exported docbook site.
>>>
>>
>> I agree.
>>
>> Perhaps we need to organize a team of editors to work on this? I volunteer
>> to be one of them. Perhaps we should figure out who is on the team and
>> create our plan and our schedule together.
>>
>> A straight export didn't work for a variety of reasons, what we have checked
>> in is a straight export followed by manual tweaking to impose structure, get
>> rid of references to things that are completely out of date, etc.  There are
>> some problems with dangling links and such, and a lot more problems because
>> the original Wiki pages were not written to be part of one document, reflect
>> various versions of things, etc. It was a significant amount of work.

I don't think we need a team of editors, all developers are
responsible for the documentation.

I think one of the mistakes we are making is the thinking that it
should be one document. It should be one web site of documentation. I
don't believe it should read as a user manual.

The first task should be just to get the content on line.

If we have plans to provide a series of documents focused to a
particular audience we can address that once things have settled.

I'm very appreciative of all the work Jonathan and others have done in
the initial export and organisation but getting it up on the web will
help everyone really see what has been done.

>> As you say, work is currently being lost. I'm not reflecting new changes to
>> the Wiki into these docs, someone will have to do this. Particularly for the
>> Java broker. So far, I don't know who is responsible for the Java broker
>> docs.

Lets just get the docbook up in a parallel mode to the wiki so we can
verify that things are not lost, from either side.
The longer we don't have docbook on the web the more pressure there
will be to do a re-export as there will be more changes on the wiki.



>> On the C++ broker side, we have lots of documents we want to contribute
>> upstream, and I think they are generally in better shape than the existing
>> Wiki information. And we're doing the new API docs upstream to start with.
>>
>>> We can work on tweeking the colours once it is live.
>>>
>>> Are we in a place where we can just export and see what it is like?
>>>
>>
>> I think what is in svn now tells you what it is like. There's a build system
>> there, so you can see what it's like. It's pretty rough, it needs editing.
>>
>> I am doing tutorial for the new API, and doing that upstream. I will also
>> contribute a lot of Red Hat docs for the C++ broker after stripping Red
>> Hat-specific stuff. Someone else needs to do the heavy lifting for the Java
>> broker and WCF docs. I hope we'll all be making changes to the docs as we
>> change the code.
>>
>> Can I sign you up as one of the editors?

Like it or not all the committers are editors. If we get the docbook
on the web then I will work to move any new content from wiki to
docbook.

>> 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
>
>



-- 
Martin Ritchie

---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org


Mime
View raw message