LinuxConf.eu: Documentation and user-space API design

LinuxConf.eu: Documentation and user-space API design

Posted Sep 5, 2007 13:12 UTC (Wed) by njs (guest, #40338)
In reply to: LinuxConf.eu: Documentation and user-space API design by arnd
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.

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.

---

(Log in to post comments)