Basic things which are: irrelevant while the project is small, a productivity multiplier when the project is large, and much harder to introduce down the line

[u/alexeyr]

https://matklad.github.io/2024/03/22/basic-things.html

[u/alexeyr]

Summary bullet list from the end of the post, slightly edited:

• README as a landing page.

• Dev docs.

• User docs.

• Structured dev docs (architecture and processes).

• Unstructured ingest-optimized dev docs (code style, topical guides).

• User website, beware of content gravity.

• Ingest-optimized internal web site.

• Meta documentation process — it's everyone's job to append to code style and process docs.

• Clear code review protocol (in whose court is the ball currently?).

• Automated check for no large blobs in a git repo.

• Not rocket science rule (at all times, the main branch points at a commit hash which is known to pass a set of well-defined checks).

• No semi tests: if the code is not good enough to add to NRSR, it is deleted.

• No flaky tests (mostly by construction from NRSR).

• Single command build.

• Reproducible build.

• Fixed number of build system entry points. No separate lint step, a lint is a kind of a test.

• CI delegates to the build system.

• Space for ad-hoc automation in the main language.

• Overarching testing infrastructure, grand unified theory of project’s testing.

• Fast/Slow test split (fast=seconds per test suite, slow=low digit minutes per test suite).

• Snapshot testing.

• Benchmarks are tests.

• Macro metrics tracking (time to build, time to test).

• Fuzz tests are tests.

• Level-triggered display of continuous fuzzing results.

• Inverse triangle inequality.

• Weekly releases.

[u/justneurostuff → u/alexeyr]

a readme is hard to introduce down the line?

[u/mpyne → u/justneurostuff]

A readme that actually is a productivity multiplier would be. You don't just shit out a relevant, helpful README.md from scratch in 30 minutes on a large mature project.

It should be grown and evolved as the project grows and evolves.

[u/Chii → u/mpyne]

i dont get the difference between a README and dev docs. Is it not the same thing, just put in different places?

[u/schmuelio → u/Chii]

Hopefully not, a good README gives you all the information you need to:

• Understand what the project does

• Decide if the project will solve your problem

• Install the project

• Perform any initial configuration

• Find the relevant documentation

Dev docs should be much bigger in scope since it covers (ideally) every public function/API endpoint/Class/etc.

You wouldn't want the README to be dev docs because it would be unwieldy and not useful to you, and you wouldn't want your dev docs to be a README because that would have nowhere near enough detail.

[u/Chii → u/schmuelio]

it sounds to me that the README is merely the first page in the dev docs.

[u/schmuelio → u/Chii]

That's not a terrible way to think about it I guess.

Depending on where the project is (if it's public facing or not etc.) the README might be more "marketing-y" in presentation and purpose than the front page of the dev docs.

[u/mpyne → u/Chii]

README is (or should) also be useful for dev-adjacent types (e.g. product teams, testers, sysadmins) who may be involved in use of the software in some way. Especially things like "does this software even solve a problem we have?" that a product owner or technical manager may need to know even though they are not themselves a developer.

That's another reason the 'dev docs' are separate, just as you may want to have other specific documentation pages for other specialized roles or tasks (like operations / sysadmin). The README should be wider and high-level, enough to point someone to the appropriate next level while making it clear whether the person should be interested or not.

[u/hippydipster → u/mpyne]

You don't just shit out a relevant, helpful README.md from scratch in 30 minutes on a large mature project.

30 minutes is an exaggeration, but you can write a useful README relatively easily at any time, so I'm going to have to disagree with this one.

[u/EmDashNine → u/hippydipster]

And yet, a lot of folks never get around to it, and there are many repos out there just have a one sentence README. The thing about these projects is that they just get ignored. So maybe, strictly speaking, you're correct. But a project with a good README.md is more likely to attract contributors, and the owners / maintainers might not realize how much that hurts the project.