[gst-devel] The 1.0 plan

[Stefan Kost]

Am 25.11.2010 13:51, schrieb Thomas Vander Stichele:
> Hi,
> 
>> One of the big missing items on this list is improving the documentation. We've
>> been thinking again about making a book for 1.0. It always boils down to the
>> fact that most core developers would gladly write a chapter or two here and
>> there but the missing part, it seems, is someone who would take charge of
>> organizing and proofreading all this. If anyone feels like taking the lead
>> here, we would be very very happy hackers.
> 
> I've been particularly thinking about this and asking around for
> opinions.
> 
> I very much liked the way the Couchdb people set up their book website
> and ended up publishing it: http://guide.couchdb.org/
> 
> a) they developed the book in a code repository
> b) they use it to tag physical releases of the book, and manage
> translations
> c) they had a site set up all the way through with some simple
> javascript so anyone could leave a comment on any specific paragraph and
> it was posted as a mail to a list dedicated to the book
> d) everything to make the book is freely available
> 
> They wrote the book in a subset of HTML5 instead of docbook, and are
> able to convert it to docbook.

I have been recently playing with ascii doc quite a bit and like the pragmatic
concepts of it. One basically write wiki-markup. It can render to html, docbook,
etc.

Also I 2nd the feedback thing. Having that for all kind of docs would rock. Need
to look at how they did that.

> 
> I don't want to overly focus on the toolchain to make a book, but I
> think c) was killer - they got lots of feedback as they wrote the book
> (even from me), which both helped them improve content as well as
> motivate the writers directly.
> 
> One practical idea for the book I thought would be good is to have
> enough simple code samples on how to do things in C, and pick a
> higher-level language (Python) and "translate" all C examples in the
> equivalent Python code.  Just as in our current manual, it would be
> important to make sure these examples compile/validate and/or run.
>

I think the way we have some of the example in our current docs is okay, its
just that probably now most people are not aware of the magic and start putting
examples directly into the docs. A few lines in docs/README docuemnting it would
be appreacited.

> 
> I'm willing to take the lead on this if we find some people that are
> willing to write specific chapters.  It'd be useful to have someone help
> us out with concrete info who's already written a book (Jono, you still
> lurking here?) We should probably start with a rough chapter outline for
> it and see who'd be up for writing some chapters.  I myself was thinking
> about doing one on synchronization for example as I'm going to make an
> internal presentation about it at Flumotion at some point.

REgarding out current docs. I would like to merge the ADM and PWG into one book.
This way we can have a common introduction (design, concepts, debugging) and we
can xref things better.
There would be two main chapters about writing apps and writing plugins.

Anyone against that idea?

Regarding the book, shall we start from scratch or turn the current manual(s)
into the book?

> 
> Who else is interested in writing part of a GStreamer book?

I'd love to contribute.

Stefan

> 
> Thomas
>