b3126044e8
- Simplify flatten_vault API to return usize instead of MigrationResult struct - Add KEEP_FOLDERS: attachments/ and _themes/ alongside type/, config/, theme/ - Use HashSet for collision tracking in unique_filename - Update wikilinks from path-based [[folder/slug]] to title-based [[slug]] - Clean up empty directories after flattening - Flatten demo-vault-v2: move all notes from type-based subfolders to root - Update smoke tests for flat vault structure - Remove migrate_to_flat_vault from repair_vault (one-time migration only) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2.5 KiB
aliases, Is A
| aliases | Is A | |
|---|---|---|
|
Topic |
Writing
Writing covers the craft of putting ideas into words clearly, consistently, and for a specific audience. It spans the mechanics of good prose, the habits that sustain a weekly publishing cadence, the editorial mindset needed to serve a technical readership, and the deeper question of what makes writing worth reading in the first place.
Why this matters
Writing is the core skill of the entire Refactoring operation. Every newsletter edition, every essay, every podcast show note, every sponsor report — all of it depends on the ability to write clearly and persuasively. Improving as a writer is the single highest-leverage investment in the business. The evergreen notes writing-for-clarity-vs-writing-for-credit and on-consistency-in-creative-work capture two foundational principles: write to be understood (not to sound smart), and show up reliably (not brilliantly once in a while). This topic connects to responsibility-content-production on the operational side and to topic-reading-books on the input side, since the best writers are always avid readers.
Key resources
- writing-for-clarity-vs-writing-for-credit — the guiding principle for all Refactoring content
- on-consistency-in-creative-work — why regular publishing matters more than occasional masterpieces
- note-on-writing-well — William Zinsser's classic, reread annually, on simplicity and humanity in nonfiction prose
- note-show-your-work — Austin Kleon's manifesto for sharing the creative process openly
- "Draft No. 4" by John McPhee — the best book on the structural craft of nonfiction writing
Notes
- The most common writing mistake in technical content is assuming the reader has the same context as the writer — good technical writing is an exercise in empathy
- Editing is where writing quality actually happens; the first draft is just raw material, and the willingness to cut and restructure separates good writers from average ones
- Writing for a weekly cadence requires accepting that not every piece will be exceptional — the consistent output matters more than individual brilliance, and the average quality rises over time through sheer practice
- Voice is the competitive moat in newsletter writing; tactics and insights can be copied, but a distinctive voice cannot be replicated
- The best way to improve as a writer is to read good writing carefully and to write frequently — there are no shortcuts, and that is both discouraging and liberating