Re: [RESEND][PATCH] Add /proc/mempool to display mempool usage

[Linus Torvalds <torvalds@linux-foundation.org>]

On Tue, 2 Dec 2008, Pekka Enberg wrote:
> 
> OK, but why do we have those different ABI "stages" in
> Documentation/ABI then? The README file there seems to contradict what
> you say. Or maybe I'm reading it wrong...

I think that whole Documentation/ABI stuff is utter tosh, and should just 
be thrown out, whenever it talks about interfaces that are _not_ ABI's.

IOW, it's fine to document things that are actually supposed to be stable, 
but:

 - assuming that non-documentation means that it's not an ABI is bogus
   and wrong.

 - explicitly documenting something as "not an ABI" is wrongheaded and 
   stupid, because it's meaningless and only sets people up for being 
   disappointed later.

So yeah, I think we might as well remove the "testing" one. Right now it 
can act in two ways:

 - as documentation on how to use it (ie as "stable").

   This is fine, but then it shouldn't be called "testing", should it?

 - as an excuse for whining later when it _did_ get used, and people break 
   exported ABI's, and we need to revert the breakage.

   And this is the one that I don't think is valid. No amount of 
   documentation will ever make something less stable.

So as far as I'm concerned, "testing" should either go away (as a way to 
discourage people from even _knowing_ about the things, and hoping that 
they never get used), or it should be moved to "stable".

And in the end, nothing is ever totally black-and-white or quite that 
simple, but that's the mindset you should have.

Finally, when it comes to documentation as a bigger issue:

 - wrong documentation is irrelevant. It doesn't matter if the 
   documentation says "X", when the code does "Y".

   If people rely on "Y", then pointing at the docs and saying "but you 
   should never have relied on it, because teh docs say X" is totally and 
   utterly bogus. The _documentation_ was wrong. Don't ever use incorrect 
   documentation as an excuse. 

Too many people seem to think that documentation is the "final" argument. 
It's not. Not even close. It's a hint and a help, but it's _secondary_ to 
code. Anybody who doesn't understand that should never be allowed to write 
code (or documentation, for that matte).

[ The same is true of assert()'s in code too - I've seen too many damn 
  asserts that were simply _wrong_, and then when they triggered, people 
  would always blindly assume that the assert() was right, and try to 
  change the code to suit. For some reason people have a hard time asking 
  themselves whether perhaps the bug was in the assertion itself. ]

			Linus