I find that having the documentation in the same file and interactive with, and having the ability to include formulae and diagrams helps immeasurably in ensuring that the documentation is updated as the code changes.
This sounds logical, yet I have never seen that in my own code, the code of colleagues at work or other code. If the documentation is not somehow automatically tested against changes in the code, the documentation in the same file is almost always worse (as in "more wrong") than adding the changes in another document. I don't know why it's easier to remember or for others to check for updates in "special" files.
Comments
I find that having the documentation in the same file and interactive with, and having the ability to include formulae and diagrams helps immeasurably in ensuring that the documentation is updated as the code changes.
This sounds logical, yet I have never seen that in my own code, the code of colleagues at work or other code. If the documentation is not somehow automatically tested against changes in the code, the documentation in the same file is almost always worse (as in "more wrong") than adding the changes in another document. I don't know why it's easier to remember or for others to check for updates in "special" files.