Documentation (was: [cairo] About cairo_show_text and UTF-8...)

[Carl Worth]

On Fri, 06 Jan 2006 15:04:52 -0500, Scott Robert Ladd wrote:
> I've done professional documentation, and I'd love to sit down and work 
> on the Cairo docs -- but can't afford to spend the time.

That sounds like a common symptom.

> Note that I've been down this road before with other free packages, and 
> it always ends in the same place -- no one seems to care about the docs! 

I don't understand your inference here. You've described about that
you care about cairo documentation, but cannot afford to work on
them. But here you generalize that missing documentation must be
caused by a lack of care?

> In my experience, free software projects don't value documentation; 
> there is a "macho" mentality that people should figure it out by 
> "reading code", and if you need (or want) docs, you're somehow a 
> technical wimp.

I won't pretend to have information on "free software projects" in
general. But it is certainly the case that with cairo we value
documentation. I don't consider cairo complete until it has complete
documentation (which it does not yet). This was the motivation for my
reminder in the 1.0 release announcement that the number 1 comes "at
the beginning". We're just not done yet with everything we want to do.

>            Nine times out of ten, I can get a question answered by 
> looking in MSDN; for free projects, I get a mish-mash of disconnected 
> man pages, incomplete HTML, and text files.

We're rapidly off-topic now. But if nothing else, I will say that
similar concerns to yours were discussed at OSDL's recent "Desktop
Architects'" meeting. Here are a couple of pointers to pieces of the
follow-up discussion about setting up some sort of "documentation portal":

http://lists.osdl.org/pipermail/desktop_architects/2005-December/000214.html

http://lists.osdl.org/pipermail/desktop_architects/2006-January/000688.html

Feel free to jump in there with any useful ideas you might have.

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060109/7ea19ca8/attachment.pgp