At Firebase (and at Google) I have done a _ton_ of work at making our "how docs" consistently correct with limited maintenance time. Consider a page like this:

At Firebase (and at Google) I have done a _ton_ of work at making our "how docs" consistently correct with limited maintenance time. Consider a page like this: https://firebase.google.com/docs/firestore/manage-data/add-data https://firebase.google.com/docs/firestore/manage-data/add-d... It has 12 "how" sections of code snippets, each with 12 language options. That means 144 code snippets need to be correct for this page to be 100% correct! And we don't auto-generate any of these snippets, since auto-generating idiomatic code is a rabbit hole that's consumed many a good developer. So we, like Etsy, have come up with a separation of concerns between How and Why that works for us. The text on the page is maintained by a tech writer. The code on the page is a series of blocks that look like this: {% includecode snippet="android_firestore_write_doc" %} We have a system that resolves these, at publish time, to match snippets on GitHub. For example: https://github.com/firebase/snippets-android/blob/5f94890d7ba329a8a4c25f0ec8b42d4b9d781bc0/firestore/app/src/main/java/com/google/example/firestore/DocSnippets.java#L318-L336 https://github.com/firebase/snippets-android/blob/5f94890d7b... These snippets can be maintained with all the wonderful tools that exist in the world for maintaining code! We don't need to think of them as just docs. So that "snippets-android" repo has continuous build, a robot that updates dependencies, PRs/Issues for third-party contributions, etc. What we've found is that this system allows us to maintain many thousands of code snippets with only a handful of people watching over them.