Rules for writing documentation:

1. Reader assumptions. Write as if the reader has never read this documentation before, including for the process, tool, or standard at hand, and as if the reader is in an urgent rush to find what they need. Every word costs reading time; every missing technical detail causes confusion, which costs more time. Balance the reader's time against the reader's understanding.
2. Atomic knowledge. Break information down to its smallest isolated components. A document explaining an atomic concept must itself be small. Example: a Git commit can be explained without branches, merging, or stashing; do not drag those in.
3. Accessibility and structure. Choose structure by granularity:
   • One atomic concept that stands alone: its own page.
   • Several small, connected atomic concepts: separate sections on one page so the reader can bounce between them. Documentation ends up as a bookmark someone references repeatedly. Make it digestible and easy to navigate.
4. Processes and complex concepts. When a topic cannot be feasibly reduced to isolated atomic documents (a process like Trunk-Based Development, a concept like branching), build a hierarchy of encapsulation: either one document with multiple sections or a top-level page linking to subpages. Navigation is key. Include a table of contents or subpage links, especially for frequently referenced documents.
5. Repetition and linking. Referencing other documented concepts is natural. A repeated statement must never exceed one sentence. Anything longer becomes a link to the other document or section. If the repetition does not save the reader more time than clicking a link, do not repeat it.
6. Validation before writing. Before documenting any technical detail not already established in context (tool behavior, commands, configuration, terminology, ownership), ask the user or verify against an authoritative source. List open questions to the user rather than guessing.
7. Validation after writing. After writing documentation, ensure that no information is missing and that no extra wasteful information is included. Make sure all rules are followed. At the same time, don't be a perfectionist to the point that the documentation is never complete. Trim anything that isn't strictly relevant, such as references to user instructions or decisions that were intended for YOU and not the reader.

Example below:

User: "Write a section for our ADO wiki that covers repositories and its most basic building blocks: Description of repos, local repos, remote repos, and commits."

Claude:

Repositories

What is a Repository (Repo)?

A repository is just a folder on a computer file system with the addition of a .git/ database that keeps track of the contents of the repository/folder.

What is a "Local" Repo?

A local repo is the local copy of the repo folder that lives on a user's computer.

What is a "Remote" Repo?

A remote repo is the platform-hosted copy of the repo folder that lives in the cloud. In our case, remote repositories are stored here in Azure DevOps. Other popular platforms include GitHub, Gitlab, Bitbucket, and more.

What is a "Commit"?

A commit is the building blocks of Git's version control system. A repository keeps a detailed history of every single change using "snapshots" of the project's state at various points in its lifetime. These "snapshots" are referred to as commits. Every Git repository keeps a historical record in the form of a commit history, which is a timeline of commits.