README

For a small project of a few one-off scripts and notebooks, a single README is more suitable than a documentation site; for projects that do not plan to do human review, AI-generated documentation will erode user trust, so it is better not to write it at all.

Python project documentation can be divided into four layers: docstrings, API reference, guides and README, and design decisions (the why); AI excels at the first and third layers, static site tools handle the second layer, and the fourth layer must be done by humans.

A README is a documentation file in the project root directory, usually containing a project introduction, installation steps, a list of environment variables, run commands, and known limitations.

The way to mitigate the risk of tribal knowledge is to externalize it into architecture decision records (ADRs), README comments, or agent instruction files.

claude.md differs from a general README in that its audience is the model rather than human readers, and it places more emphasis on executability and constraints.

The core of improving documentation is completing the context by providing specific commands, version-checking methods, and common pitfall tips, rather than simply increasing the length.

In the paid tests, almost all testers got stuck at the same point, especially during the environment setup stage.

Implicit assumptions should be made explicit by clearly stating all prerequisites, version requirements, environment variables, and execution directories in the documentation.

Strictly executing a README word-for-word in a clean virtual machine or container can simulate most problems encountered in a new user environment.

When a project collision occurs, one should honestly state the differentiated positioning at the top of the README, such as the language used and the features focused on.