home / skills / baz-scm / awesome-reviewers / documentation
This skill helps teams document code effectively by writing clear inline comments and up-to-date project docs that explain intent and decisions.
npx playbooks add skill baz-scm/awesome-reviewers --skill documentationReview the files below or copy the command above to add this skill to your agents.
---
name: documentation
description: Communicating the intended behavior and context of code through clear documentation and comments, and sharing knowledge with the team.
version: '1.0'
---
# Documentation & Knowledge Sharing
Effective developers write code and documentation. This includes inline comments explaining non-obvious code and higher-level docs that describe modules and systems. Good documentation ensures that knowledge is shared, onboarding is easier, and future maintainers understand the rationale behind decisions. In 2025’s collaborative environments, this skill is invaluable for team velocity.
## Examples
- Writing a README for a project that explains how to set it up and the overall architecture.
- Adding a comment in code to clarify why a workaround is used, or marking a section as deprecated with explanation.
## Guidelines
- **Comment for Clarity:** Add explanatory comments where code isn’t self-explanatory – for example, to clarify complex algorithms, workarounds, or important decisions. A brief comment can save others (and your future self) lots of time understanding the code’s intent.
- **Keep Docs Up-to-Date:** Treat documentation as a living part of the code. Whenever code behavior changes, update relevant comments and docs accordingly. This prevents misleading information. Inline code comments should always reflect the current state of the code.
- **Project Documentation:** Adhere to your project’s documentation standards for things like API docs, developer guides, or maintainers lists. For instance, if contributing to an open-source project, ensure files like `OWNERS` are updated properly to reflect component maintainers. Proper docs ensure transparency and smooth knowledge transfer.
This skill focuses on communicating intended behavior and context of code through clear documentation and comments, and on sharing knowledge across the team. It emphasizes making codebases easier to understand, maintain, and extend by documenting rationale, usage, and system-level decisions. Good documentation reduces onboarding time and preserves institutional knowledge in collaborative, agent-assisted workflows.
Inspect code to find areas where intent, trade-offs, or non-obvious behavior are not documented and add concise comments or higher-level docs. Create or update README, architecture notes, API docs, and contributor guidance so they reflect current behavior and setup. Mark deprecated areas, add maintainers lists, and ensure inline comments explain workarounds or complex algorithms.
How detailed should inline comments be?
Inline comments should be brief and explain intent, trade-offs, and non-obvious reasons. Avoid restating code; focus on why something is implemented a certain way.
When should documentation be updated?
Update documentation whenever code behavior, public interfaces, or operational procedures change. Prefer making doc updates in the same change that modifies code to keep them synchronized.