|
| 1 | +--- |
| 2 | +name: front-loading |
| 3 | +description: Put the answer first, then context and details follow. Use when writing documentation, tutorials, error messages, or any communication where readers need to decide quickly if something is relevant to them. |
| 4 | +--- |
| 5 | + |
| 6 | +# Front-Loading |
| 7 | + |
| 8 | +Put the answer first. Context follows. |
| 9 | + |
| 10 | +## What This Is |
| 11 | + |
| 12 | +Front-loading means leading with the most important information. Users decide in the first few words whether to keep reading. |
| 13 | + |
| 14 | +Structure your communication as: |
| 15 | + |
| 16 | +1. **The point** (first sentence) |
| 17 | +2. **Why it matters** (next 1–2 sentences) |
| 18 | +3. **Details and evidence** (rest of content) |
| 19 | + |
| 20 | +Most writers do the opposite: context first, then conclusion. Readers get lost in the journey before reaching the destination. |
| 21 | + |
| 22 | +## When to Use |
| 23 | + |
| 24 | +- Writing documentation or guides |
| 25 | +- Structuring arguments or explanations |
| 26 | +- Creating tutorial sections |
| 27 | +- Writing error messages |
| 28 | +- Composing email or feedback |
| 29 | +- Organizing any sequential information |
| 30 | + |
| 31 | +Front-load at every level: sentences, paragraphs, sections, documents. |
| 32 | + |
| 33 | +## How to Apply |
| 34 | + |
| 35 | +### 1. Lead with the Conclusion |
| 36 | + |
| 37 | +Put the answer first. Don't make readers wait. |
| 38 | + |
| 39 | +**Bad (context first):** |
| 40 | +"There are many different ways to approach testing. Some teams test before writing code. Others test after. Some tests run quickly, others take longer. The most important thing is consistency. So you should write tests." |
| 41 | + |
| 42 | +**Good (conclusion first):** |
| 43 | +"Write tests. Consistency matters more than approach." |
| 44 | + |
| 45 | +Then explain the trade-offs if needed. |
| 46 | + |
| 47 | +### 2. Answer the Reader's Question Immediately |
| 48 | + |
| 49 | +Readers have a question in mind. Answer it in the first sentence. |
| 50 | + |
| 51 | +**Bad (makes reader wait):** |
| 52 | +"Syncpack is a CLI tool built in Rust. It uses a configuration file in JSON format. The configuration file specifies rules for how to synchronize dependencies. These rules can be customized per workspace..." |
| 53 | + |
| 54 | +Reader's question: "How do I configure Syncpack?" Buried in paragraph 3. |
| 55 | + |
| 56 | +**Good (answers immediately):** |
| 57 | +"Configure Syncpack in `.syncpackrc.json` at your monorepo root. Specify version groups and rules for each." |
| 58 | + |
| 59 | +Then explain each option. |
| 60 | + |
| 61 | +### 3. Use Signposting |
| 62 | + |
| 63 | +Tell readers what's coming before they read it. |
| 64 | + |
| 65 | +**Bad (no preview):** |
| 66 | +"First, install Node 18. Then, verify the installation. Next, clone the repository. After that, install dependencies..." |
| 67 | + |
| 68 | +Reader: "Where is this going?" |
| 69 | + |
| 70 | +**Good (preview structure):** |
| 71 | +"Three steps: Install Node, clone the repo, and run `npm install`." |
| 72 | + |
| 73 | +Then detail each step. |
| 74 | + |
| 75 | +### 4. When Explaining a Process, Show the End State First |
| 76 | + |
| 77 | +Let readers know what success looks like before they start. |
| 78 | + |
| 79 | +**Bad (journey without destination):** |
| 80 | +"Follow these 12 steps to set up CI/CD. Step 1: Create a workflow file. Step 2: Add a trigger. Step 3: Define a job..." |
| 81 | + |
| 82 | +Reader: "Why am I doing this?" |
| 83 | + |
| 84 | +**Good (end state first):** |
| 85 | +"Goal: Your PR automatically runs tests and fails if any break. Here's how to set it up in 12 steps." |
| 86 | + |
| 87 | +Then detail steps 1–12. |
| 88 | + |
| 89 | +### 5. Structure Paragraphs with Topic Sentence First |
| 90 | + |
| 91 | +Each paragraph's first sentence should be its main idea. |
| 92 | + |
| 93 | +**Bad (idea buried):** |
| 94 | +"There are many different caching strategies. Some store values in memory. Others use disk. Still others use remote services. The strategy you choose depends on your use case. For most applications, in-memory caching is sufficient." |
| 95 | + |
| 96 | +Reader has to parse the whole paragraph to find the point. |
| 97 | + |
| 98 | +**Good (topic first):** |
| 99 | +"For most applications, in-memory caching is sufficient. Other strategies (disk, remote) exist for specific cases. Choose based on your performance and persistence needs." |
| 100 | + |
| 101 | +### 6. When Providing Options, Lead with the Recommendation |
| 102 | + |
| 103 | +Don't make readers compare three options to find the best one. |
| 104 | + |
| 105 | +**Bad (no guidance):** |
| 106 | +"You can use approach A, B, or C. Each has trade-offs. A is simple but inflexible. B is flexible but complex. C is somewhere in between. Most projects use B or C." |
| 107 | + |
| 108 | +Reader: "So which should I use?" |
| 109 | + |
| 110 | +**Good (recommendation first):** |
| 111 | +"Use approach B (flexible but complex). It scales as your needs grow. Use approach A only if simplicity is critical. Approach C rarely adds value." |
| 112 | + |
| 113 | +## Examples |
| 114 | + |
| 115 | +### Documentation Section |
| 116 | + |
| 117 | +**Bad (context first):** |
| 118 | +"The registry client handles communication with npm. Over time, performance became an issue. We realized the client was making unnecessary requests. After analysis, we found that caching solved the problem. So the registry client now caches responses." |
| 119 | + |
| 120 | +**Good (point first):** |
| 121 | +"The registry client caches npm responses to improve performance. This reduced request overhead by 60%." |
| 122 | + |
| 123 | +Then explain the details. |
| 124 | + |
| 125 | +--- |
| 126 | + |
| 127 | +### Error Message |
| 128 | + |
| 129 | +**Bad (generic context):** |
| 130 | +"An operation has encountered an error condition. The system attempted to perform a task. This task requires certain prerequisites. One or more prerequisites were not met. Please verify your setup." |
| 131 | + |
| 132 | +**Good (specific answer):** |
| 133 | +"Missing required field in config: 'versionGroups'. See `.syncpackrc.json` example." |
| 134 | + |
| 135 | +--- |
| 136 | + |
| 137 | +### Tutorial Section |
| 138 | + |
| 139 | +**Bad (setup before goal):** |
| 140 | +"Before you can run Syncpack, you need to set up your monorepo structure. This involves creating a root directory. Inside this directory, you need workspace packages. Each package should have a `package.json`. Once you have this structure, you can run Syncpack." |
| 141 | + |
| 142 | +**Good (goal first):** |
| 143 | +"Goal: Run Syncpack to sync versions across your monorepo." |
| 144 | + |
| 145 | +Then list the prerequisites (monorepo structure, workspace packages). |
| 146 | + |
| 147 | +--- |
| 148 | + |
| 149 | +### Workflow Documentation |
| 150 | + |
| 151 | +**Bad (steps without outcome):** |
| 152 | +"Step 1: Write your implementation. Step 2: Write tests. Step 3: Run tests locally. Step 4: Push to GitHub. Step 5: Wait for CI. Step 6: Address failures. Step 7: Merge when green." |
| 153 | + |
| 154 | +**Good (outcome first):** |
| 155 | +"Goal: Merge code only when tests pass and CI approves." |
| 156 | + |
| 157 | +Then list the steps to reach that goal. |
| 158 | + |
| 159 | +## Trade-offs |
| 160 | + |
| 161 | +### When NOT to front-load |
| 162 | + |
| 163 | +- **Narrative/storytelling:** Sometimes the journey is the point. Build suspense if appropriate. |
| 164 | +- **Teaching from first principles:** Some explanation is necessary before jumping to conclusions. |
| 165 | +- **Building trust:** Sometimes context _is_ the point (e.g., "here's why we made this decision"). |
| 166 | +- **Sensitive feedback:** Sometimes leading with criticism is harmful. Lead with understanding instead. |
| 167 | + |
| 168 | +The principle: **Match the reader's mental model.** If they need context to understand the conclusion, provide context first. |
| 169 | + |
| 170 | +### Common mistake |
| 171 | + |
| 172 | +Over-front-loading: "Use this. End of story." without any reasoning alienates readers who need understanding. |
| 173 | + |
| 174 | +Solve by asking: "Will the reader understand why this conclusion is right?" If no, provide enough context. But lead with the conclusion, not the context. |
| 175 | + |
| 176 | +## Testing |
| 177 | + |
| 178 | +How to know if you've front-loaded effectively: |
| 179 | + |
| 180 | +1. **First sentence test:** Can someone read only the first sentence and understand the main point? |
| 181 | +2. **Skim test:** Someone skims headings and bullets—do they get the gist? |
| 182 | +3. **Reader expectation test:** "What happens next?" readers predict after each section. Were they right? |
| 183 | +4. **Reduction test:** Remove everything after the first paragraph. Is the main point clear? (If yes, you front-loaded successfully.) |
| 184 | +5. **Fresh eyes test:** Have someone read the first paragraph and summarize. Did they get it right? |
| 185 | + |
| 186 | +## Application in Syncpack |
| 187 | + |
| 188 | +Front-loading improves: |
| 189 | + |
| 190 | +- **Skill descriptions:** Users know instantly if it's relevant |
| 191 | +- **Error messages:** Users understand what failed and how to fix it |
| 192 | +- **Documentation sections:** Readers find what they need faster |
| 193 | +- **Code comments:** Maintainers understand the "why" before the "how" |
| 194 | +- **Commit messages:** Reviewers know the intent before reading code |
| 195 | +- **Proposals or plans:** Stakeholders see the recommendation before the analysis |
| 196 | + |
| 197 | +Every document you write is a race against the reader's attention span. Front-load to win that race. |
0 commit comments