skills/research-writing/references/documentation_explainer_patterns.md

# Documentation and Explainer Patterns

## Match document type to user need

### Concept
What is this? Why does it work?

### Tutorial
How can I learn this through a guided example?

### How-to
How do I complete this task?

### Reference
What are the exact fields/options/commands?

### Troubleshooting
Why is this failing and how do I diagnose it?

### Architecture guide
How should the system be structured and why?

### Migration guide
How do I move safely from old to new?

## Audience

Define:
- prerequisite knowledge;
- environment;
- role;
- goal;
- what can be omitted.

## Procedures

A strong procedure includes:
1. prerequisites;
2. starting state;
3. numbered steps;
4. expected result;
5. validation;
6. rollback/recovery when material.

Start steps with imperative verbs where natural.

## Commands

Clearly separate:
- command;
- placeholder;
- expected output;
- warning.

Never hide secrets in examples.

## Concepts

A concept page should:
- define the concept early;
- explain why it matters;
- give a mental model;
- show one concrete example;
- identify limits/edge cases.

## Troubleshooting

Structure:
- symptom;
- likely layer;
- decisive check;
- evidence;
- fix;
- validation.

## Maintenance

Version/date sensitive docs should identify:
- product version;
- API/SDK version;
- last verified date where appropriate;
- source of truth.