LinuxConf.eu: Documentation and user-space API design [LWN.net]

LinuxConf.eu: Documentation and user-space API design

Posted Sep 4, 2007 23:05 UTC (Tue) by arnd (subscriber, #8866)
In reply to: LinuxConf.eu: Documentation and user-space API design by njs
Parent article: LinuxConf.eu: Documentation and user-space API design

One point that Michael made in his talk was that it's useful to have the
documentation written by somebody other than the author of the code, in
order to increase the chances of finding bugs in the process.

Of course the requirement of having a documentation for everything is a
very good idea nonetheless and having both written by the same person can
only be better than no documentation at all.

Another problem we still need to work on is documentation for all the
existing code -- it's hard to make documenting new stuff a requirement
when there are so many examples of where we haven't done the documentation
in years. This is even more true for kernel internal interfaces than for
user APIs.

(Log in to post comments)

LinuxConf.eu: Documentation and user-space API design

Posted Sep 5, 2007 13:12 UTC (Wed) by njs (guest, #40338) [Link]

>One point that Michael made in his talk was that it's useful to have the documentation written by somebody other than the author of the code, in order to increase the chances of finding bugs in the process.

Sure. But everyone also keeps saying that schemes that involve too much overhead won't fly -- and reasonably so, it's already very hard to find patch reviewers, requiring patch submitters find someone to write up docs for them before their patch can be accepted may just be unworkable. So I was wondering if one could get 80% of the benefit with 5% of the work.

(Note that I'm only suggesting the patch author write up example code, documentation proper could well still be done by someone else.)

>Another problem we still need to work on is documentation for all the existing code -- it's hard to make documenting new stuff a requirement when there are so many examples of where we haven't done the documentation in years. This is even more true for kernel internal interfaces than for user APIs.

Don't know if I believe this... it's totally common for projects to say "hey, we used to do things such-and-such way, we've realized it was a bad idea, from now on we're doing them differently" and to grandfather in the old stuff in the process. And internal interfaces are both less stable and more aimed at experts, so the documentation/design problems are far less urgent.