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>
28 lines
2.5 KiB
Markdown
28 lines
2.5 KiB
Markdown
---
|
|
aliases: ["Writing"]
|
|
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
|