Documentation?

[Patrick O'Donnell]

>From: Glynn Clements <glynn at gclements.plus.com>
>Date: Tue, 7 Apr 2009 19:44:19 +0100
>
>Patrick O'Donnell wrote:
>> 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.
>
>Oh? Would you care to elaborate? Like, what is *actually* missing?

The first thing to come to mind is a guide to what's even in that
directory.  If you already know what all the abbreviations and
initializms are, then you can probably find what you're looking for
without too much trouble.  If not, it's pretty much hit-and-miss.

Also, something to glue all the pieces together -- to tell the
application programmer where each piece fits in the whole puzzle,
where to use it, when to use it, and equally important, when not to.
Something like the old Xlib Programmer's Guide.  Reference information
where you must infer the API from protocol specs is hard enough to
grok.  Trying to put together a coherent big picture from the
scattered bits takes a lot of time that someone trying to get a
product out the door doesn't have.

>> I have made similar queries on this list for
>> documentation, with similar lack of results.
>
>IOW, you ask, people answer, you don't like the answer (probably
>because you didn't ask the right question in the first place), then
>claim that no-one answered.

IOW, I ask, people answer a different question, and they blame me for
not asking the question they wanted to answer in the first place.
Then, they claim the answered my question.  Hmmmm....