Re: Coordination for developer documentations

[Sébastien Wilmet <swilmet gnome org>]

On Tue, Mar 04, 2014 at 07:05:30PM +0100, Frederic Peters wrote:
> I was mostly concerned by our technical infrastructure for developer
> documentation, but that itself has of course been driven by the
> content we produced (or wanted to produce), so I don't think they can
> really be separated.

For the content, what is really needed in my opinion is a good and 
recent book on GLib and GTK+. GTK+ 3 is maybe too unstable for writing a 
book, but GLib (including GObject and GIO) is stable enough. It could be 
a simple update of an existing book, such as The Official GNOME 2 
Developer's Guide.

The book should also be freely available on the web, with a free license 
(Creative Commons for example).

If the book focus on the C language, it makes sense to write also 
chapters on how to write good libraries, how to design good APIs with 
GObject, what are the best practices, etc. This is something less well 
documented. And this can also be beneficial for internal code in 
applications, not just libraries.

----

Another thing, I see sometimes on IRC some questions about how to use a 
certain API, or questions on some details not documented. Ideally when 
such a question is answered, the API documentation should be improved at 
the same time, so it benefits other people. I don't know if such small 
improvements are often done, but if everybody takes the time to write 
patches for the documentation when a problem is encountered, the 
documentation will get better over the time.

Best regards,
Sébastien