Documentation and comments

One of the things that come up at work is documentation. I've had conversations with peers about how I should have known about things "because it had been documented in the wiki" or something like that. A large part of the time the thing I should have known about wasn't even right.The problem with documentation and comments in code is that they very quickly age. The root cause is that we developers we get paid to write code and deliver features. Comments and documentation, insofar as they make the immediate goal more reachable, is a good thing; writing a doc to go over in a design review makes the design review work a lot better.Once the features have been delivered, well, now it's a different story.As developers, we get paid to write code and deliver features -- this is how we are measured. Documentation, be it in comments or something more formal, is not part of the measurement scheme. Documentation for past features even less so.Over time I came to the habit of checking the last edit date of docs I read. Documents older than a year since the previous edit were to be taken with a big grain of salt. Documents three years or older I just assume to be dead and wrong. Same with comments: check the edit history and if the code changed with no corresponding comment change, well, just assume the worse and read the code and ignore the comments.How can we change this: measure developers on documentation. Will this ever happen? Unlikely. Should this happen? Probably not. What can you do to make this better? Write clear code. Code is for humans to read, make sure it's readable.