Documentation?

[Patrick O'Donnell]

>Date: Tue, 7 Apr 2009 16:50:26 +0100
>From: Alan Cox <alan at lxorguk.ukuu.org.uk>
>
>> Someone offered up www.x.org/docs, which may be fine for X Window
>> System developers, but is not what most application programmers would
>> call documentation.
>
>Why would an application programmer want to be using Xlib directly ?

Frankly, you're right.  Today.

Unfortunately, I'm in the position of supporting a substrate for
several mission-critical applications that has seen two and a half
decades of development based on Xlib.  (... with all the assumptions
that entails built in to more layers of the system than was warranted
even at the time, but...)  I don't have the luxury of ripping all that
out and replacing it with cairo/pango with all the learning curve,
development time, and regression testing that would entail.  Our team
does not have the time budget for anything like that.  Our customers
are a very conservative lot, too, and do not react well if we need to
tell them to change their systems just becase a new version of some
library we're depending on comes out.  Stability is crucial.  (Did I
mention "mission-critical".)

Realize that the Xlib portion of my job description is a small
fraction of my duties.  The Xlib applications are the most stable of
our suite, and other than trying to (now) track X.Org changes in basic
functionality, the development on that portion of our code is nil.
Development of new tools and applications (not on Xlib, by the way)
takes priority by far.

I'd be very surprised if I was alone in this situation.


>There is good documentation for things like pango and cairo but then
>you've clearly not looked. I would imagine nobody bothered to reply to
>such queries because they though you should learn to use a search engine.

Being condescending and insulting is not helpful.  Cairo/pango is not
what I was looking for.

What would /you/ call it if you asked me for help to find a hammer --
which failed to appear in hours of searching -- and I don't bother to
answer because I think you don't know how to search for a screwdriver?
I would at least be more helpful if I suggested that a screw would be
a better fastener than a nail (no one even mentioned cairo/pango as a
possible help to me -- until your snideness mentioned them), but if
you really had to use the nail for some reason, the hammer is what you
need.

In a fairer universe, I'd be able to step up and offer the time
necessary to learn the changes and write the documenation folks like
me seek for X.Org.  Though, that may be the help that is needed --
I've been told more than a few times that documentation I write is not
easily understood :-(.  I'd be happy if I had the time to support the
back-compatibilty in X core functionality that we're depending on.
Alas, this universe is not so kind.