Documentation (was: [cairo] About cairo_show_text and UTF-8...)
Scott Robert Ladd
graphics at coyotegulch.com
Fri Jan 6 12:04:52 PST 2006
Carl Worth wrote:
> Yes, the documentation is still quite inadequate. I will be the first
> to admit that. And I am embarrassed that we have had "1.0" out for
> this long and still haven't finished the documentation.
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. Working on
Cairo docs is unlikely to attract any business my way, and no one is
paying bounties for tech writers on free projects.
Please excuse a slight rant...
Free software won't make many in-roads into professional software
development so long as the documentation is inadequate. Yet I've found
little or no interest in anyone *supporting* documentation work. I see
lots of small bounties for technical features, but not one about the
docs -- for *any* GPL project, in *any* amount.
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!
Except, of course, users, who are not steeped in whatever mysteries went
into creating a package.
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
I'm not necessarily picking on you or Cairo; the problem is systemic to
free software. I'm just wondering *why* companies like Novell and Sun
don't put a bit of funding behind documentation. Microsoft certainly
does, and buries people in megabytes of cross-referenced, detailed
materials. 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.
Okay, rant off.
Bottom line: I'd be more than happy to apply my skills to Cairo and GTK+
documentation, if I wouldn't starve my family doing it.
Scott Robert Ladd <scott.ladd at coyotegulch.com>
Coyote Gulch Productions
More information about the cairo