documentation

Document code decisions with concise, co-located explanations.

22|6|Updated Feb 11, 2026

Search Tags:#documentation #adr #docstrings #code-comments #architecture-decisions #readmes

Ready to run

npx skills add https://github.com/yuchenzhu-research/zhihu-scraper --skill documentation-yuchenzhu-research

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: documentation
Source: https://github.com/yuchenzhu-research/zhihu-scraper/tree/main/references/skills/engineering/engineering-progression/documentation
Command: npx skills add https://github.com/yuchenzhu-research/zhihu-scraper --skill documentation-yuchenzhu-research

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Documentation is often neglected or out of date, making it hard to understand code rationale. This Skill guides teams to write concise, purpose-driven documentation that captures why decisions were made, what constraints shaped the design, and how to maintain alignment with code.

Core Features & Use Cases

Co-locate rationale with code: ADRs, READMEs, and inline notes that explain why decisions were made.
Domain-language consistency: align terminology across code and documentation.
Lightweight governance: simple guidelines to keep docs current as code evolves.

Quick Start

Create a concise ADR and attach a short README update that explains the rationale behind the design decision.

Frequently Asked Questions about documentation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

What is the best way to document code rationale for long-term maintainability?▼

Document code rationale by co-locating concise explanations of design decisions directly with the related code. This practice applies to inline comments, docstrings, ADRs, and READMEs to ensure long-term maintainability.

How do I write an Architecture Decision Record to explain design constraints?▼

Write a concise ADR that captures why specific decisions were made and what constraints shaped the design. Attach a short README update to explain the rationale and maintain alignment with the evolving codebase.

Why do code comments and docstrings go out of date and how to prevent it?▼

Documentation goes out of date when it lacks lightweight governance and co-location with code. Prevent drift by applying consistent terminology, concise language, and simple guidelines to keep docs updated as code evolves.

What should be included in a README to align domain language with code?▼

A README should include concise explanations of code rationale and align domain terminology across code and documentation. This ensures shared understanding and reduces confusion across software projects.

When do I need an ADR versus inline code comments for architecture decisions?▼

Use ADRs to capture broader architecture decisions and constraints, while inline code comments explain specific local logic. Both require concise language and co-location with related code to improve project maintainability.