Documentation should explain why things are the way they are. With sufficient effort, you can look at a piece of code to figure out what algorithm it implements

Documentation should explain why things are the way they are. With sufficient effort, you can look at a piece of code to figure out what algorithm it implements, but there is no amount of reading that will tell you why that algorithm is the right one to use. There should be a way to trace this "why" all the way up to the business reason. Documentation should also provide mental shortcuts. Rather than forcing you to figure out what algorithm the code implements, it could just tell you. It should also tell you things that are surprising, and might accidentally miss or misinterpret. Documentation should tell you information that you can't just as easily glean from the code. A `doTransmorgification()` method doesn't need the comment `// does transmorgification`. Documentation shouldn't attempt too tell you everything with one form of documentation. Documentation on a line or method or class is good for one sort of information, but it doesn't cover the overall architecture of the program. That is often best left as a separate piece of documentation. It should consider the reader. Is the reader looking for an introduction to how to use this library, or are they looking for what property the method has in some edge case? Documentation should use the easiest to follow, least technical language it can without being inaccurate. It's not an academic paper; it's an explanation to your fellow developer. Documentation should tell you how the responsibilities are divided up in the code. If you implement an interface, will you need to record metrics or will that be handled for you? Documentation should cover any processes you need to follow when making certain kinds of changes. If you need to do something in two separate deploys, those steps should be written down.