Some notes: I'd generally try to disregard the fear that your docs won't be used. At worst, they'll allow people to determine the original design intent and re

Some notes: I'd generally try to disregard the fear that your docs won't be used. At worst, they'll allow people to determine the original design intent and reconstruct how and why the project diverged at some point after you stop working on it. As long as the docs are part of the version control scheme for the project, you should be fine. If you however are using "share drive version control" aka a bunch of copies of the documentation for each release on a network drive separate decoupled from the project, it might as well not exist. If that's the case, you need to get it in version control. Sorry that was a bit of a tangent but I had flashbacks to a previous project. If you want people to read the documentation, make it concise. The ADRs can be verbose and logged as necessary. That's kinda the point of an ADR. They record the mindset and intent of the developer. Everything else however needs to be easy to jump into. Have a super concise summary that links to subtopics and put in the detail there. If you want people to maintain the documentation, integrate it into the build system/CI. If you have code examples in your documentation, they need to be unit tested so that the build system will warn you when the docs are out of date. Another avenue is to associate documentation with source code so that merge checks require documentation associated with modified sections of code must be checked off before commit. Getting this right is definitely the hardest part with documentation but when done well, it is immediately evident. Also I know I have seen articles like you mentioned but for the life of me I can't find them. If you come across them, I'd love if you could share some so that I can bookmark them.