Writing docs isn't hard, but maintaining a well-documented ecosystem is quite difficult. The aim of docs should be to limit reverse engineering time, or at a hi

Writing docs isn't hard, but maintaining a well-documented ecosystem is quite difficult. The aim of docs should be to limit reverse engineering time, or at a higher level should provide direct impact on velocity of a given team member. When I first started out I would keep big centralized documentation stores. If a project had a dedicated wiki then I'd use that, but if that wasn't present I'd throw together something on my internal note taking like Obsidian. The downside of centralized and detached documentation is that it's hard to check per pull request if it's been updated, so it relies on regularly fallible human processes. Second, code and architecture tend to drift, and it's difficult to stay on top of that drift with a centralized doc store. I then gravitated towards in-repository documentation. I'd open up a /docs folder and either include a static site to be run locally or configured to run on the web. I haven't seen a ton of downsides for this approach other than that it will skew respiratory metrics if you keep them. Changes in the docs folder can be prompted and checked for in pull requests. The only potential downside is when your software spans multiple repositories of different types. A deployment repo here, code repos there - have one store of your documentation in the application repository means you treat most (if not all) other repositories as generic and document them as such so they neatly fit into your software docs. None of this even begins to touch on documenting inline, which is fairly key to maintaining good code. For all the churn and hand-wringing I see about when to document which is often phrased as when not to document, this is the chief barrier I see software engineers hit their head on. When you're working on a package / module / library it's easy to substantiate lots of implicit context that's easy to admit during this process. I follow this pretty loose framework: - document inputs and outputs - document error conditions - document package purpose, intended use This direct documentation should then be backed up by more implicit documentation like variable / function naming conventions and tests. Testing is all about maintaining contracts; not attaining "coverage". Though it is possible that tests are not only reinforcing trust for end users; I do generally trust tests in PRs but only so far as I know I won't break my users as opposed to being "bug free". Really thorough testing that instills my confidence involves other methods like fuzzing.