Lot of this is outdated. Including stuff that made a lot of sense in the past like diataxis and the google guidance.
I've started to build docs structured as a skill. Since every model/harness is trained to handle skills well today. The entire docs of a project or modeled as a skill.
I also have additional frontmatter on the md files. Specifically 2 keys -> when should you read, when you should not read this doc. This with a simple cli to help parse this has made the docs experience much quicker and nicer.
You can also generate svgs, mermaids etc on the fly now when you are really stuck on something.
I think it's worth more scrutiny today, rather than less. Your claude code can barf out "a rewrite" but is it any good? So far the answer is "no" (see anthropic's C compiler, or a more recent port of bun).
Software is still the best specification for existing behavior..
I'm not following because a) The bun rewrite was a success b) the C compiler wasn't a rewrite and c) "Software is still the best specification for existing behavior" seems to imply that rewrites are achievable because we already have a working version that functions as a spec?
I've started to build docs structured as a skill. Since every model/harness is trained to handle skills well today. The entire docs of a project or modeled as a skill.
I also have additional frontmatter on the md files. Specifically 2 keys -> when should you read, when you should not read this doc. This with a simple cli to help parse this has made the docs experience much quicker and nicer.
You can also generate svgs, mermaids etc on the fly now when you are really stuck on something.