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.

▲

lopatin an hour ago | parent | next [-]

Referencing Joel Spolsky's article about how you should never do a rewrite is starting to feel outdated as well.

▲

tra3 an hour ago | parent [-]

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..

	▲	lopatin an hour ago \| parent [-]
		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?

▲

blanched 2 hours ago | parent | prev | next [-]

Why do you think diataxis and the google guidance is outdated now?

▲

esafak 2 hours ago | parent | prev [-]

Why is diataxis outdated; don't your engineers ever read the code? Don't you think it helps the agents too?

▲

Tsarp 2 hours ago | parent [-]

Its just far easier to ask an agent to do the first past ( with references to actual code ) and then start to dig in.

A good implementation of something like this is https://deepwiki.com/ for OSS projects.

	▲	esafak an hour ago \| parent [-]
		The code doesn't usually capture the whys; that is what documentation is good for.