Linus on the value of documentation:
You seem to put a lot of trust in a piece of documentation.(link)
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.
2 comments:
Lets seem how useful the Microsoft documentation is to the Samba folks?
My experience with big-corp doc is as Linus describes. However that need not be the way. As I recall, at Burroughs back in the early 1960's, the design process for the entire B5000 computer system architecture was formalized - design and documentation were written together, before the line between hardware and OS were even decided. (Should functionality "X" be part of the CPU, and what should be in the OS?) This way they could optimize performance by 'hardwiring' a function where it was demonstrably most useful in a running software system. In essence, the documentation was the design.
Post a Comment