[Grok-dev] Re: [website] Let's do content!

[Martijn Faassen]

Noah Gift wrote:
> 
> On Jan 3, 2008, at 2:12 PM, Martijn Faassen wrote:
> 
>> Noah Gift wrote:
>>> On Jan 2, 2008, at 1:47 PM, Martijn Faassen wrote:
>> [snip]
>>> There is nothing like getting free help on documentation!  This was a 
>>> brilliant idea for Django, who regardless of your feelings about 
>>> their framework, did documentation at a level that should be aspired to.
>>> http://www.djangobook.com/en/1.0/chapter01/
>>
>> The reason we want to get to a Plone-based website is to get more help 
>> on documentation. :)
>>
>> Does Django allow online commenting or editing? I see a comment 
>> feature, but please tell us more!
> I noticed that Django had a great strategy, as I mentioned in another 
> email, of documenting a book first, publicly.  People could comment on 
> the book, but not edit the book.

All right. I think commenting but not editing would be a good step to 
introduce too.

> Since I am writing a book currently 
> for O'Reilly, I know that we are using docbook.  I have no idea how an 
> author would proceed on trying to do a write once open book though, as 
> that seems tricky, especially with Plone.  I guess it might have to be 
> cut and pasted, but still giving people the ability to at least comment 
> is a great idea.  I suppose having some wikipedia style system to allow 
> people to edit would be very helpful too, as you could get some great 
> real world tricks.

Comments first, then the other stuff. Note that for the tutorials right 
now we're using restructured text. This is a structured form of 
plain-text and should be convertable into docbook or particular forms of 
latex or whatever a hypothetical publisher would require.

The current idea would be to maintain the longer tutorial/book on the 
filesystem with a normal text editor, and have a script to push it into 
Plone when ready. We'd not do editing on the website itself for this. We 
*do* want to encourage people to upload smaller documents onto the 
website though in the form of howtos, faqs or tutorials, etc.

> The first impression for people new to Django of having a complete, and 
> extremely accurate book online for people is tremendous to say the 
> least.  This is a model to follow for Open Source Projects, and flips 
> traditional book writing on its head.  I think it also leads to a better 
> incentive for authors to document their project, as they are finally 
> getting paid for their work as they do it.

Actually years ago the Zope project went the same way, and the Zope Book 
was maintained online with a commenting facilities and so on. It was at 
some point also published. Then the book got out of date as Zope changed ...

That negative note aside, I'm personally not that interested in getting 
paid at this point. I mean, I wouldn't object to getting paid of course, 
but I am more interested in expanding the documentation to help make 
Grok more popular and improve Grok itself.

Regards,

Martijn