documentation-structure
Skill0 starsChanged 3 days agoMITView on GitHub
Documentation structure and information organization standard. Requires establishing overall understanding first, then expanding details item by item, and finally consolidating public reference information.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- canonical/snapcrafttheir own version, first seen Oct 8, 2026
- miroapp/miro-aitheir own version, first seen Apr 28, 2026
- canonical/workshoptheir own version, first seen Jul 21, 2025
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- canonical/snapcraft★ 1.3ksame name
- miroapp/miro-ai★ 154same name
- canonical/workshop★ 137same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository17 other files it gives its agents.
- .cursor/rules/engineering-context.mdcCursor rule
- change-report-deliverySkill
- code-asset-inventorySkill
- data-audit-reproducibilitySkill
- data-first-executionSkill
- engineering-context-completenessSkill
- engineering-transparencySkill
- explicit-instruction-fidelitySkill
- interface-contractSkill
- language-expressionSkill
- production-loggingSkill
- repository-publication-hygieneSkill
- task-execution-governanceSkill
- technical-documentationSkill
- testing-verificationSkill
- unfinished-work-trackingSkill
- user-intent-prioritySkill
The file
We split this skill into the rules it gives an agent
3 rules. 0 are common, 3 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 11
All documentation should follow a progression from shallow to deep.
- Distinctive: line 91
After the reader already understands each module, introduce public content in a unified way.
- Distinctive: line 141
When the detailed part needs to reference information from the overview, continue and expand from it directly rather than copying it again.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Documentation Structure and Information Organization Standard
I. Core Principle
All documentation should follow a progression from shallow to deep.
For system, project, and module technical documentation, prefer:
Part One: Overview
Part Two: Detailed Description
Part Three: Public Reference
A specific document may be adjusted according to its theme, but it must not break the natural order in which the reader understands the information.
II. Part One: Overview
First let the reader understand the complete composition.
For a system containing modules A, B, and C:
A. Module A
Introduce:
- Module name.
- Location.
- Brief function description.
- Main responsibilities.
B. Module B
Introduce:
- Module name.
- Location.
- Brief function description.
- Main responsibilities.
C. Module C
Introduce:
- Module name.
- Location.
- Brief function description.
- Main responsibilities.
The overview must cover all major components.
Provide as needed:
- Overall flow diagram.
- Module relationship diagram.
- Data flow.
- Main dependency relationships.
The overview must not pile up large amounts of implementation detail ahead of time.
III. Part Two: Item-by-Item Detailed Description
Expand in the order given in the overview.
Each module is introduced according to the actual situation:
- Module introduction.
- Functional responsibilities.
- Usage scenarios.
- Input data.
- Input data structure.
- Processing logic.
- Output data.
- Output data structure.
- Core functions.
- Function call relationships.
- Upstream modules.
- Downstream modules.
- External dependencies.
- Exception handling.
- Testing and verification methods.
Different modules adopt a consistent organization method.
Inapplicable content may be omitted; content must not be fabricated for the sake of template completeness.
IV. Part Three: Public Reference
After the reader already understands each module, introduce public content in a unified way.
Include as actually needed:
- Public data models.
- Enumeration definitions.
- Public field definitions.
- Shared interfaces.
- Public functions.
- Global configuration.
- Public exception types.
- General rules.
- Shared dependencies.
Public content must state which modules use it.
V. Organizing Workflow Documentation
For workflow documentation, prefer:
Part One: Overall Objective
Introduce the problem the workflow solves and its final objective.
Part Two: Workflow Overview
Present in actual execution order:
- Each stage.
- Stage responsibilities.
- Input data.
- Output data.
- Important files.
- Relationships between modules.
Part Three: Detailed Execution Process
Introduce the implementation of each stage in actual execution order.
VI. Avoiding Repetition
Forbidden:
- Creating a module summary table with identical content after the overview has already fully shown the modules.
- Explaining the same fields repeatedly across multiple chapters.
- Re-listing files and inputs and outputs that the flow diagram has already clearly shown.
- Mechanically adding summary chapters for the sake of formal completeness.
- Repeatedly introducing the same background.
- Expressing the same concept under multiple different names.
When the detailed part needs to reference information from the overview, continue and expand from it directly rather than copying it again.
VII. Flexible Adjustment According to Document Type
Different documents use the structure that suits them.
- API documentation: interface overview → interface details → public models.
- Data documentation: data system overview → data file details → public field definitions.
- Project documentation: project overview → module details → public reference.
- Deployment documentation: deployment overview → operational steps → parameters and reference.
- Troubleshooting documentation: problem symptoms → troubleshooting process → causes and solutions.
VIII. Final Check
Check:
- Is the complete composition introduced first?
- Is the overall understanding established first?
- Does the detailed description expand in the order of the overview?
- Are public definitions placed in a suitable location?
- Are there any duplicate chapters?
- Is necessary information missing?
- Has redundant content been created for the sake of the template?
IX. Final Principle
The overview shows the whole picture, the detailed description goes deep into the implementation, and the public reference consolidates shared definitions.
Let the reader first know what the system consists of, then understand how each part works, and finally consult the shared definitions.
Information should be fully expressed once, in the most appropriate location.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

