[samayylmao]

I work at an organization where we build mostly internally used tools to support different products/service lines. Here's what I've been advocating for and it works fairly well without requiring a lot of time to write documentation that is, often out of date. I find mileage varies as some people always just ask a senior engineer and never look at the documentation.

We have a high level wiki page about each application/micro service we support. Things like - resource locations - job schedules, purposes, inputs/outputs -FAQ's - known dependencies on other micro services, etc

We also have wiki pages for - onboarding - team norms and expectations (pr process, on-call duties, coding conventions, etc)

Inside each application's or micro service's repo the readme should have steps to - get the project running locally. - document feature flags - document conventions unique to that project - document how to trigger a release

Someone here said the code should be the source of truth and other documentation isn't needed. To me it's unclear what they mean by that exactly; I could get behind that if they are documenting via comments on functions/classes/etc. my org tends to not write much comments in the code so it's really hard to tell if the code does what it was intended to do or if there is a bug. What I love to see for "self documenting" code is tests. You write tests to either test for outcomes you expect or test outcomes that you don't expect, don't happen.