Ok. Clearly I am joking. Well half joking, at least.
Everything rots. Rotten documentation is never good documentation, even if it started out that way. Your projects contents will rot in this order:
External documentation is almost useless after any amount of time; So don't write it. Having bad documentation is worst then have no documentation. A confused developer is far more dangerous then a developer that isn't sure of something.
There are things that need to be documented, but don't think of them as documentation. If you have an API layer, you should write a spec sheet. And I mean do this before you implement your API. Sure it will change, then updated it. But once your API is locked down, you don't have to worry about changing your sheet. Bonus points for using generated documentation like Swagger
Side Note: And for the love of god, dogfood your API!
Readme's can be important, they gain the benefit of being easier to change since they are sitting in the repo(and are hopefully markdowns). Anytime I see anything documented in Word or PDFs I worry(and cry). The bigger the cost of change, the less it will get changed. Readme's should really include abstract things, and how to get the project running. Avoid implantation details, anything that might change.
CHANGELOG and TODO files can be good, but only if you remember to update them. There are ways to generate changelogs from git and todo's from comments. Prefer this over manual.
As a rule don't comment your code. If you have to comment your code, you should rewrite/refactor your code so that its apparent of whats going on. This will improve your codes maintainability and remove your comment rot. Win/Win. Self-documenting code is pretty much the only thing that will survive the test of time in any given project.
- Namespaces should describe context
- Classes should describe resources
- Functions should describe actions.
- Helper Functions should describe simple actions.
- Paragraphs( or blocks) of code should be of a single thought.
- Sentences( or Lines) of code should be doing a single thing. [If I have to think about the order of operations, your doing it wrong]