Linus on Documentation

I was going through a thread on an ACPI issue with nForce4 on the kernel list. An interesting set of bits from Linus Torvalds hurled at Rafael Wysocki.

You seem to put a lot of trust in a piece of documentation.

Do you realize how those pieces of paper are written? They are written by
people who have absolutely *nothing* to do with the actual implementation,
and whose job it is to write documentation. And while the people who
actually do the programming etc are supposed to help them, the two parties
generally detest each other.

Technical writers hate the “real engineers” for not helping them, and the
“real engineers” tend to dislike having to be pestered to explain their
stuff and have to read through some document that isn’t meant for them,
but that they need to sign off on.

In other words: please do *not* expect that the documentation actually
matches reality. You seem to think that the documentation came first
and/or is quite accurate. That’s not at all likely to be true.



  1. This is exactly why at GE we ask SW guys to write their own docs. Cut out the middlemen. I would call this a best practice :)))


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s