[cairo] Re: Documentation
rjshaw at netspace.net.au
Fri Jan 6 17:45:50 PST 2006
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
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.
More information about the cairo