S> Conventional wisdom among tech writers is of course that
S> programmers, engineers, etc. couldn't produce a coherent
S> paragraph if their lives depended on it. They're just too far
S> off in their weird space to ever explain anything clearly.
Let's not get off topic here: We are _not_ proposing documenting a KDE
app, we are proposing to document 1.6 million lines of advanced C
constructs used in a production-quality Linux kernel with 1302 compile
options. Anyone looking at these docs does not expect sugar coating
and no amount of technospeak should upset them. Kernel programming is
not for the casual user, it is an advanced topic. We can produce a
few end-user chapters, such as how to configure _some_ of the kernel
options and the recompile/install guide, but 90% of what is needed is
engineer-to-engineer communications papers, not "kernel for dummies".
What we need, and which will be the hardest to get, is not for the
programmers to open their schedule books for us, but to get them to
dilligently follow the GNOME commenting style --- if every function,
or at least every public function of every C source file were to have
a 'proper' comment block, kernel docs would be self-generating. That
should be our goal. Anything else and we are faced with the same
instant obsolescence that thwarted the previous kernel doc projects.
As for LyX/LinuxDoc, please don't go there. Don't even think it.
DocBook is the standard in so many places, and LinuxDoc is fading
fast. This has been hashed to death on the LDP mailing list and if
you need convincing, please grep those archives and do not repeat
history here. If you feel compelled to make a system which even fools
can use, you will find only fools will want to use it.
FWIW, and to echo Sandy's comments, in my 25 years experience in
commercial programming, any engineer who cannot produce a coherent
paragraph and/or explain their work to their spouse or their kids does
not really understand their own work; they are posers, not
programmers.
Good programmers know the historical reason we use C is because it is
_human_ readable; bad programmers, on the other hand, like to hide
behind the myth of job security through obscure coding, and I have
seen so many of these people blacklisted from the industry, it is a
wonder the myth persists.
-- Gary Lawrence Murphy <garym@linux.ca>: office voice/fax: 01 519 4222723 T(C)Inc Business Innovations through Open Source http://www.teledyn.com M:I-3 - Documenting the Linux kernel: http://kernelbook.sourceforge.net Free Internet for a Free O/S? - http://www.teledyn.com/products/FreeWWW- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/