markdown
- Write like you're explaining to a competent peer, not selling to a novice (no handholding).
- State facts directly and cut everything that doesn't add information.
- Assume the reader is smart enough to infer context and figure things out.
- Use ATX-style headings (i.e.,
# Heading 1,## Heading 2, etc.) instead of Setext-style (Heading 1\n=========). - Use
markdownlintto lint markdown files.markdownlint --disable MD013 -- <somefile.md>- if not installed, install with
npm install -g markdownlint-cli markdownlint --disable MD013 --fix <somefile.md>to auto-fix issues.
numbered lists should be contiguous
- Do not attempt to continue numbered lists across titles; examples below.
### title 1
1. thing
2. thing
### title 2
<!-- this does not work; it should start on 1 again -->
3. other thing
4. other thing
represent folder hierarchies with bulletpoints
Avoid using code blocks with tree structures; they're hard to edit and maintain.
project/
├── src/
│ ├── task.py
│ └── config.py
└── pyproject.toml
Prefer bulletpoint lists; they're more easily editable by humans.
- project/
- src/
- task.py
- config.py
- pyproject.toml
- src/