Re: Cassandra documentation (and in this case the datastax anti-entropy docs)

[Eric Evans <ee...@rackspace.com>]

On Thu, 2011-03-31 at 18:57 +0100, Nick Telford wrote:
> I don't think the Wiki is the right place for community maintained
> user docs; it doesn't have the necessary structure. 

The wiki is great at what wikis are great at, lowering the barrier to
contribution.  There is a lot of good stuff (some of it is even
translated to other languages!); I'm guessing there would be much less
if people had to jump through more hoops.

> Perhaps some generated docs maintained in-tree and hosted somewhere on
> cassandra.apache.org might be an idea? This would also enforce some
> order over changes made to them as changes would be controlled by
> committers and managed through JIRA. 

I had this exact idea, I even checked the CQL language documentation
into the tree as doc/cql/CQL.textile.  I had expected that to either set
a precedent, or to be told to get it out of there, but neither
happened. :)

I don't think we need to choose one or the other.  If someone would
rather add documentation to the wiki, we should let them (thank them
even).  People interested in something maintained with more rigor can
invite the wiki peeps to submit patches, and steal their content if they
won't!  

-- 
Eric Evans
eevans@rackspace.com

Re: Cassandra documentation (and in this case the datastax anti-entropy docs)

[Diallo Mamadou Bobo <ex...@gmail.com>]

Hi.
I also believe that wiki are not so good for a community managed wiki even thought it is used as "de facto" tool for opensource projects doc.

I suggest that we use drupal's book module, it is really full featured and easy to use.

I would be happy to do some wireframing and set-up a demo if neccessary.


Envoyé de mon iPhone

Le 1 avr. 2011 à 01:27, Nick Telford <ni...@gmail.com> a écrit :

> I agree that wikis are great for contribution; what I meant was that they're
> rather poor at organising information for ease of discovery, especially by
> new users.
> 
> I still like the idea of some more structured docs being managed by the
> community though.
> 
> On 1 April 2011 02:16, Eric Evans <ee...@rackspace.com> wrote:
> 
>> On Thu, 2011-03-31 at 18:57 +0100, Nick Telford wrote:
>>> I don't think the Wiki is the right place for community maintained
>>> user docs; it doesn't have the necessary structure.
>> 
>> The wiki is great at what wikis are great at, lowering the barrier to
>> contribution.  There is a lot of good stuff (some of it is even
>> translated to other languages!); I'm guessing there would be much less
>> if people had to jump through more hoops.
>> 
>>> Perhaps some generated docs maintained in-tree and hosted somewhere on
>>> cassandra.apache.org might be an idea? This would also enforce some
>>> order over changes made to them as changes would be controlled by
>>> committers and managed through JIRA.
>> 
>> I had this exact idea, I even checked the CQL language documentation
>> into the tree as doc/cql/CQL.textile.  I had expected that to either set
>> a precedent, or to be told to get it out of there, but neither
>> happened. :)
>> 
>> I don't think we need to choose one or the other.  If someone would
>> rather add documentation to the wiki, we should let them (thank them
>> even).  People interested in something maintained with more rigor can
>> invite the wiki peeps to submit patches, and steal their content if they
>> won't!
>> 
>> --
>> Eric Evans
>> eevans@rackspace.com
>> 
>> 

Re: Cassandra documentation (and in this case the datastax anti-entropy docs)

[Nick Telford <ni...@gmail.com>]

I agree that wikis are great for contribution; what I meant was that they're
rather poor at organising information for ease of discovery, especially by
new users.

I still like the idea of some more structured docs being managed by the
community though.

On 1 April 2011 02:16, Eric Evans <ee...@rackspace.com> wrote:

> On Thu, 2011-03-31 at 18:57 +0100, Nick Telford wrote:
> > I don't think the Wiki is the right place for community maintained
> > user docs; it doesn't have the necessary structure.
>
> The wiki is great at what wikis are great at, lowering the barrier to
> contribution.  There is a lot of good stuff (some of it is even
> translated to other languages!); I'm guessing there would be much less
> if people had to jump through more hoops.
>
> > Perhaps some generated docs maintained in-tree and hosted somewhere on
> > cassandra.apache.org might be an idea? This would also enforce some
> > order over changes made to them as changes would be controlled by
> > committers and managed through JIRA.
>
> I had this exact idea, I even checked the CQL language documentation
> into the tree as doc/cql/CQL.textile.  I had expected that to either set
> a precedent, or to be told to get it out of there, but neither
> happened. :)
>
> I don't think we need to choose one or the other.  If someone would
> rather add documentation to the wiki, we should let them (thank them
> even).  People interested in something maintained with more rigor can
> invite the wiki peeps to submit patches, and steal their content if they
> won't!
>
> --
> Eric Evans
> eevans@rackspace.com
>
>