|
| 1 | +# How to write “Explanation” (discussion) docs |
| 2 | + |
| 3 | +Below is a procedural guideline / checklist that an AI (or human writer) should follow when asked to write an “explanation” style document in a larger documentation system. |
| 4 | + |
| 5 | +1. Decide the topic boundary / scope |
| 6 | + |
| 7 | +Choose a topic that merits a deeper dive — something that benefits from understanding rationale, trade-offs, alternatives, history, or context. |
| 8 | + |
| 9 | +Avoid topics that are already covered well in “how-to” or “reference” docs, unless you are elaborating the “why behind them.” |
| 10 | + |
| 11 | +Define the intended audience: users who already know the basics and want more insight. |
| 12 | + |
| 13 | +Limit the scope: don’t try to explain everything, just pick one coherent theme or area (e.g. “caching strategies for the platform,” or “why environment variables are handled this way”). |
| 14 | + |
| 15 | +2. Provide context and motivation |
| 16 | + |
| 17 | +Start with why this topic matters: what problem, challenge or question it addresses. |
| 18 | + |
| 19 | +Give background: prior states, constraints, historical evolution — how did we arrive here? |
| 20 | + |
| 21 | +Define key concepts or terminology as needed (briefly, without turning into a reference). |
| 22 | + |
| 23 | +3. Explore alternatives (and trade-offs) |
| 24 | + |
| 25 | +Describe possible different approaches or designs, even those not chosen. |
| 26 | + |
| 27 | +Compare and contrast: pros, cons, when one might be more suitable than another. |
| 28 | + |
| 29 | +If opinions or community debates exist, mention them, present reasoning for different sides. |
| 30 | + |
| 31 | +4. Explain rationale and design decisions |
| 32 | + |
| 33 | +For each major choice, explain why it was made (constraints, priorities, trade-offs). |
| 34 | + |
| 35 | +If there are technical constraints (performance, security, backwards compatibility, user expectations), surface them. |
| 36 | + |
| 37 | +Where appropriate, show consequences (positive and negative) of choices. |
| 38 | + |
| 39 | +5. Include illustrative examples or metaphors |
| 40 | + |
| 41 | +Use analogies, metaphors, or stories to help understanding (as Divio uses “cooking” as an analogy) |
| 42 | +docs.divio.com |
| 43 | + |
| 44 | +Use diagrams or conceptual visuals if helpful (to illustrate relationships, flows, architecture). |
| 45 | + |
| 46 | +6. Maintain a discursive style (not instructional) |
| 47 | + |
| 48 | +Do not give explicit “step 1, do this; step 2, do that” instructions. |
| 49 | + |
| 50 | +Do not list API syntax, method signatures, or detailed parameters (those belong in reference). |
| 51 | + |
| 52 | +Use more narrative style: “we think about …”, “alternatively …”, “one could consider …”. |
| 53 | + |
| 54 | +7. Structure the document logically |
| 55 | + |
| 56 | +Use headings/subheadings (e.g. “Motivation / Background”, “Alternatives”, “Rationale”, “Examples / Illustrations”, “Implications”). |
| 57 | + |
| 58 | +Progress from general → specific: first big picture, then deeper dives. |
| 59 | + |
| 60 | +You might end with “When this is useful / implications / further reading”. |
| 61 | + |
| 62 | +8. Link to related docs |
| 63 | + |
| 64 | +Provide references (links) to corresponding how-to guides, reference pages, or deeper technical specs. |
| 65 | + |
| 66 | +Encourage the reader to “see also” for performing actions, APIs, or tutorials. |
| 67 | + |
| 68 | +9. Be neutral, clear, and well-reasoned |
| 69 | + |
| 70 | +If you present multiple opinions, try to balance them fairly; if you prefer one, explain why. |
| 71 | + |
| 72 | +Avoid jargon without explanation. |
| 73 | + |
| 74 | +Keep paragraphs reasonably sized; use examples to break up abstract discussion. |
| 75 | + |
| 76 | +10. Review for scope creep and redundancy |
| 77 | + |
| 78 | +Check that you didn’t slip back into instructional or reference mode — if there is instruction, consider moving it to a how-to. |
| 79 | + |
| 80 | +Ensure you didn’t duplicate content from tutorials or reference; if overlap, prefer referencing instead of rehashing. |
0 commit comments