[cairo] Re: Documentation

[Russell Shaw]

Scott Robert Ladd wrote:
> 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.

I spent many hours in making a documentation patch detailing the cairo
api and how the porter-duff rendering works, only to have it ignored.
Other suggestions for gtk improvements have also been ignored.

I value internals documentation, but it is non-existant for gtk and
pango.

When non-existant documentation raises the learning curve to a certain
level, it's easier to write your own libs that you can be intimately
familiar with and does everything better, faster, and with *far* less
but more elegant code.