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

[Bryce Harrington]

On Fri, Jan 06, 2006 at 03:04:52PM -0500, Scott Robert Ladd wrote:
> 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.

You have a point, but thankfully things are not quite so stark.  There
*are* at least some open source projects which do place value on docs.
As just one example, at Inkscape we place extremely high value on
documentation and consider the people who write, maintain, and translate
them to be on par with coders, testers, and other contributors, and
treat documentation patches with the same degree of appreciation as
translation, code, or art patches.

IMHO, because of taking this view, Inkscape has been able to go from
essentially zero documentation when the project started a couple years
ago, to having half a dozen quite good tutorials, an exhastive online
manual, and a wiki full of developer and advanced user info.  This
wasn't an accident; we knew at the start we had a documentation problem
so deliberately encouraged and valued users who contributed to it.

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

As it happens, OSDL (my daytime employer) is looking to try to put
together an "ISV Developer Documentation Portal" along the lines of
MSDN.  This request came from the participants at the Desktop
Architect's Conference a month ago, and now with the holidays behind us,
folks at work are talking about trying to set something up.

My one concern with this echos your own observation - how will people be
motivated to write documentation?  The people most qualified to write it
will be too busy either writing more code or earning a living.
Unfortunately, corporations are not endless wells of money, and I
suspect they note that their income is driven more by new features than
by new docs.

One idea I've kicked around is this - OSDL has good relationships with a
number of magazine editors, many of whom are on a monthly lookout for
good new content.  Many of these publications pay their writers $300-350
for the work.  So one idea would be for OSDL to find topics needing
documenting, then recruit an expert writer for that topic, and put them
in contact with a magazine editor that wants that content and would pay
for it.  Our one condition would be that the material be provided under
an open source license a month or two after publication.

Does this sound like something of interest?

Bryce