Re: [AD] Docs and set_gfx_mode

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

On 2004-09-23, Chris <kcat@xxxxxxxxxx> wrote:
> >One of the reasons that I chosed Allegro is that the docs
> >are good. I can't say, however, that there are no space for
> >improvements.
> 
> Of course. And please, feel free to continue pointing out what
> you think should be improved.

No, the docs are shit, really. Many people deluded by the general
lack of quality in documentation (sometimes the docs themselves)
praise the quality of the manual, which was written by a bunch
of drunk naked bastards playing piano with their left feet while
practicing origami with coloured toilet paper.

I certainly can't prove that last sentence, but the first is true,
and I keep sending documentation patches to demonstrate it.

Christer, all the questions you ask are valid and show that the
documentation was written by programmers for programmers. This means,
you should be glad there is documentation at all, and you must look
at the source code to figure out how things work if something is
not clear.

By trying to teach other people with the manual you are requiring a
higher level of documentation quality which has to be written with
a different set of mind.  The set of mind which, instead of trying
to write as less sentences as possible to get the job done, tries to
figure out what a newbie might be thinking when reading those lines
for the first time and telepathically anticipate possible questions.

Please join TADIM (The Allegro Documentation Improvement
Movement).  The best thing you could do is rewrite the description
of set_gfx_mode just as you like it best without regards for
maintaining any existing crap there might be. Once you have your
version, please post a diff against the current WIP documentation
(see end of http://alleg.sourceforge.net/onlinedocs/en/ahack.html).
If patches are too troublesome, you could put your file with the
changes on some web and tell us the link so we can get the changes
and comment on them.

Thanks for your emails and keep them coming. Hopefully I didn't
sound too much of a lunatic. Ah, it's one of those days... yes.