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

[Scott Robert Ladd]

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 
technical wimp.

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

-- 
Scott Robert Ladd <scott.ladd at coyotegulch.com>
Coyote Gulch Productions
http://www.coyotegulch.com