[XML-SIG] understanding the sources. wher to start?

paul@boddie.net paul@boddie.net
16 Jun 2002 15:22:49 -0000

Rodrigo Senra <rodsenra@gpr.com.br> wrote:
>|On Thu, 13 Jun 2002 11:52:14 -0400
>|Paul Tremblay <phthenry@earthlink.net> wrote
>> In fact, good documentation is so important for all software and
>> all platforms. I use linux, and I am absolutely frustrated at
>> the terrible documentation.
>This is not a flame, but I'm curious to know
>that "...linux has terrible documentation" in comparison to what
>operating system ? 

I also use Linux, but while some applications and tools have excellent
documentation, there are many areas which are not adequately covered at all. For
example, I want to buy a USB-based CD burner, but it isn't exactly obvious where
to find reliable/definitive information on which devices are compatible, or even
which kernels are most appropriate - can I stick with a 2.2 series kernel, or do
I have to upgrade to a 2.4 series kernel? Moreover, the recommended FAQ and "how
to" documents are either dated, don't provide the required information (usually
because it's a large job to do so), or are deficient in both respects.

Thankfully, some people provide services to fill the holes in the "official"
documentation. I appreciate this because it takes initiative and a lot of effort
on the part of those people, and I suppose it's only appropriate to reciprocate
by offering one's own documentation on subjects that one is familiar with.

>I think Python "suffers" from such abundance of choices too.
>Therefore, I second the need of a comparative documentation, but
>I blame no one, except perhaps me for not doing it myself.

I usually write documentation so that I can remember how I achieved things in
the programs that I have written. Sometimes this only occurs after I first have
had to work out how simple things could be done with the technologies concerned.
If we can remove the seemingly unnecessary investigation process at the most
elementary levels (such as: how does one create documents with the DOM API in an
implementation-independent way?), Python will become a much more acceptable
mainstream choice for XML processing in the future.