nangongwentian-fe/progressive-disclosure-docs

Progressive Disclosure Docs

Use this skill to make documentation easy for both humans and agents to discover, load, and act on. Preserve the target document's language and style unless the user asks to change it.

Core Rule

Structure documentation like Agent Skills:

| Layer | Purpose | Document Equivalent | | ---- | ------- | ------------------- | | Discovery | Decide whether to read | Filename, title, summary, table of contents | | Activation | Complete the common task | Scope, decision rules, shortest working path | | Execution | Handle details only when needed | Commands, config blocks, examples, troubleshooting | | References | Keep depth available without clutter | Links to topic docs, appendices, source docs |

Never expand an existing document just because it is nearby. Put content where a future reader would naturally look for it.

Workflow

1. Inspect existing docs before editing.

   • Check filenames, headings, and current scope.
   • Identify the intended reader and task for each candidate doc.

2. Classify the new content.

   • Deployment flow
   • Business logic or domain behavior
   • Architecture or infrastructure
   • Troubleshooting evidence
   • Coding or documentation rules
   • Reference material or examples

3. Choose placement.

   • Update an existing doc only when the new content directly supports that doc's primary topic.
   • Create a new topic doc when the content introduces a second theme, a different reader, or a reusable decision model.
   • Keep the original doc as a navigation point when it only needs to mention the new topic.

4. Write from shallow to deep.

   • Start with what the doc is for and when to use it.
   • Put the common path before edge cases.
   • Put long commands, full configs, historical evidence, and rare cases after the main path.
   • Link to deeper docs instead of embedding unrelated detail.

5. Verify structure.

   • The title matches the content.
   • Each section belongs under the title.
   • A future reader can find the doc by filename.
   • Removing a section would not reveal that it belongs in another doc.

Split Or Keep

| Signal | Action | | ------ | ------ | | A section introduces a new topic | Create a new doc and link to it | | One doc serves different reader intents | Split by task or audience | | Config or logs dominate a process doc | Move details to a topic doc or appendix | | The filename no longer predicts the content | Rename or split | | The user corrects document placement | Record the rule and update the structure | | The content is a short note directly supporting the doc | Keep it in the existing doc |

Document Shape

Prefer this shape for topic docs:

# Clear Topic Name

One short paragraph: what this doc covers and when to use it.

## Summary

Key decisions or current facts.

## Common Path

The shortest safe workflow.

## Details

Config, commands, examples, or deeper explanation.

## Verification

How to know it worked.

## Related Docs

Links to adjacent topics.

For rule docs, use:

# Rule Name

## Core Principles
## Classification Rules
## Checklist
## Examples
## References

Do not force these templates when the repo already has a stronger local convention.

Anti-Patterns

Avoid:

• Adding architecture rules to deployment docs.
• Adding one-off troubleshooting transcripts to top-level docs.
• Creating notes.md, misc.md, temp.md, or other vague filenames.
• Hiding key decisions under historical logs.
• Duplicating the same rule across multiple docs.
• Treating a long README as the only place every detail must live.

File Naming

• Use lowercase English filenames with hyphens for Markdown docs: artemis-video-gateway.md.
• Use a Chinese or project-native title when that helps readers.
• Make the filename describe the stable topic, not the date or temporary task.
• If a doc is environment-specific, include that in the filename only when it changes the content meaning.

Output Expectations

When editing docs:

• State which doc was created or updated.
• Mention if content was moved out of an inappropriate doc.
• Keep unrelated docs untouched.
• Run a lightweight validation such as git diff --check when working in a git repo.