I forget the terminology, but there's a good "grid" breakdown of documentation types (I think this one: https://documentation.divio.com https://documentation.di

I forget the terminology, but there's a good "grid" breakdown of documentation types (I think this one: https://documentation.divio.com https://documentation.divio.com ) that I've simplified a bit for the internal documentation I'm involved with. * README, HOWTO, INFO, PROJECT, DESIGN, NOTES, FAQ When I pull down a `git` repo, I read the `README.md` (of course). I make my own `NOTES.md` (eg: `.gitignore`'d) of what commands, environment variables, useful blog posts, search results, whatever. Rarely do I share or encourage sharing of `NOTES.md` wholesale, but it's helpful to be able to pull out a few snippets or re-orient myself when coming back to that software/project. Then, other documents get prefixed with "HOWTO-Do-Some-Specific-Thing.md", or "INFO-Some-Particular-Component.md". "PROJECT-...", and "DESIGN-..." are "dangerous" ones in that they can quickly fall out of date, but they can be very useful while they're being actively managed. I guess personally I've started making sure to include dates or "eras" in the title, eg: "PROJECT-[2024-Feb]-Add-Foo-Support.md" or "DESIGN-[2024-02-14]-...". Stuff that's outlived its usefulness can probably be moved to an `ARCHIVE/...` in case you need it later, but keep it out of the way from confusing newcomers 1-3 years from now. "FAQ-..." almost never comes into play (hopefully) b/c it should mostly get absorbed into "HOWTO-..." or product improvements, and few products seem to rise to the level of needing FREQUENTLY asked questions. Ideally FAQ's would "go away" with work on the product or other documentation, but I've had some success with it as like sales-oriented (and ideally: sales-managed) FAQ / Canned Customer Response learnings. Putting it all together you get something like: * README.md * HOWTO-Backup-to-S3.md * HOWTO-Backup-to-BackBlaze.md * HOWTO-Manage-Existing-Backups.md * HOWTO-Exclude-Frequently-Changing-Files.md * INFO-Supported-Backup-Systems.md * PROJECT-[2024-Feb]-Backup-9000.md * DESIGN-[2024-Jan]-Auto-Backup-Detection-and-Failover.md * NOTES.md (private!) * FAQ-Residential-Customers.md * FAQ-Business-Customers.md * FAQ-Backup-Recovery-Issues.md Generally, they wouldn't all be "git-adjacent", but `README.md` should link to the other sources, `HOWTO-...` and `INFO-...` is generally good for your wiki/confluence/"published" documentation. PROJECT, DESIGN, and FAQ are all best as "loose" shared docs. Multiplayer by default with low barrier to edit/contribute. Sometimes DESIGN could be INFO-Design-..., or DESIGN might even be a DIAGRAM. You'll know it when you see it. Prefixing the documentation with the TYPE has been super-critical in adoption. It clarifies that it's not "DOCUMENTATION-About-Some-Thing.md", but instead "HOWTO...(you're gonna do something, goal-oriented)", or "INFO...(you're gonna learn something, no specific outcome)". If you START introducing new prefixes, then you'll hopefully see them propagate (as appropriate), but ideally whatever vocabulary your business/team ends up using is small (~5-10 documentation types) would cover a good 80-90% of your use cases, and they should be brain-dead simple enough that it's clear their categorization is useful.