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

LinuxConf.eu: Documentation and user-space API design

Posted Sep 4, 2007 19:37 UTC (Tue) by njs (guest, #40338)
Parent article: LinuxConf.eu: Documentation and user-space API design

Surely it would not be too much to ask people submitting patches to write, if not documentation in English, at least documentation in code?

I mean, they're testing their patch somehow, usually with some ugly hacked up code. It would not be dramatically more work to just require them to additionally meet basic code cleanliness standards, exercise the full interface, and always send in the code? Then at least one person has had to bang their head against using the interface, and there is some kind of full specification written down (even if not in the most convenient form)...

(Log in to post comments)

LinuxConf.eu: Documentation and user-space API design

Posted Sep 4, 2007 23:05 UTC (Tue) by arnd (subscriber, #8866) [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.

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.

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.