This guide helps standardize project documentation and developer logs for clarity, consistency, and searchability.
Use it to keep technical writing concise, readable, and easy to grep.
All files should be named for maximum searchability and sorting.
Stick to this format:
YYYY-MM-DD-hhmm-short-hyphenated-description.md- Use only lowercase letters and hyphens.
- Avoid camelCase or underscores unless essential for clarity.
- Descriptions should be brief and directly relevant.
2025-06-25-0003-argon2-integration-part-iii.md2025-07-01-0430-security-hardened-and-argon2-bug-fixed.md
A predictable structure helps readers scan and understand quickly.
Follow this order for most logs and docs:
- Top-level header:
# Dev Log 2025-07-01 04:30 Argon2 Auth Bug Fixed & Security Hardened - Use "Dev Log" or "Documentation" as prefix for easy search.
- Main section headers:
## - Use
###or####for subsections if needed. Never go deeper.
Every document should include some or all of these sections.
Start each with a one-line summary if possible to add context:
- Goals (or Review/Overview):
State what you plan to do, or summarize what was achieved. - Actions & Steps (or Implementation/Workflow):
List the concrete actions taken—use a flat, single-level list.
If there are several phases or topics, split with###subheaders. - Result:
Summarize the outcome or current state. - Next Steps:
Note immediate follow-ups or TODOs. - Issues / To Do or Loose Ends (optional):
List open bugs, challenges, or future work. - Reference to Past Log (optional):
Add links to earlier docs or logs if needed.
Formatting should never get in the way of content.
Keep things simple and avoid visual noise:
- Hyphen lists only, never nested.
If you feel the urge to nest, use a subheader instead. - Numbered lists only for steps that must be followed in order.
- Fenced code blocks (
```) for all code, commands, or configs. - Headings: Never deeper than
####. All headings should be short and functional. - Use italics with underscores if needed for emphasis.
Avoid bold or inline code for section headers. - Minimize inline comments and avoid extra whitespace.
Keep your logs findable—by both people and tools.
- Store dev logs in
/documentation/dev-logs/. - Run logs and related files should have their own subfolders.
- Use strict, descriptive file naming for easy search.
- Add links to related docs or logs at the end if useful.
This table gives you the rules at a glance.
| Element | Rule |
|---|---|
| Filename | YYYY-MM-DD-hhmm-short-hyphenated-description.md |
| Top header | # Dev Log [datetime] [title/focus] |
| Headings | ## main, ### or #### for clarity, never deeper |
| Lists | Hyphens only, never nested |
| Numbered lists | For order only, no sub-numbers |
| Code | Fenced code blocks |
| Emphasis | Italics (underscores), rarely |
| Directory | /documentation/dev-logs/ |
| Related docs/links | List at end if relevant |
Note: This file itself is a great example of how to use these rules! Good documentation is readable and scannable. Running text at the start of each section is encouraged for clarity, especially in complex logs or reports.
A few points for further tweaking (if you ever feel like noodling more with this file):
- You could clarify in “Formatting Rules” that “Avoid bold” means not even for emphasis in running text—just to set expectations for newcomers coming from other orgs.
- If you ever have non-English contributors, you might want a note on language (e.g., “Write all docs in English unless explicitly agreed otherwise.”)
- You could mention version control (“All docs should be tracked in git, with meaningful commit messages”) if that’s part of your workflow.
- Every doc is an interface for future-you and your collaborators.
- Favor clarity, consistency, and brevity.
- Aim for instant grep-ability and zero ambiguity.
End of guide.