本文由 AI 分析生成
建立時間： 2022-06-22
Summary
EN: Tom Johnson (idratherbewriting.com) applies systems thinking — the discipline of understanding complex interdependencies rather than isolated components — to developer portals. He argues that documentation is not a collection of independent pages but an ecosystem where each new document affects all others (new terms change semantics, new APIs invalidate existing instructions). Technical writers who develop a “systems thinking” perspective can add unique value by understanding and managing these emergent interactions, though this comes at a productivity cost.
ZH: Tom Johnson 將系統思維（理解複雜相互依賴而非孤立元件的學科）應用於開發者入口網站。他認為文件不是獨立頁面的集合，而是一個生態系統——每份新文件都影響其他文件（新術語改變語義，新 API 使現有說明失效）。培養「系統思維」視角的技術寫作者可透過理解這些湧現互動來創造獨特價值，但代價是個人生產力。
Key Points
- Systems thinking: focuses on emergent properties and interdependencies that can’t be observed in isolated parts
- Developer portals as ecosystems: every new document is an “invasive species” that may displace or conflict with existing content
- Regression testing metaphor: new docs should be checked against existing docs (like code regression tests) — rarely done in practice
- Technical writers’ generalist nature positions them well for systems thinking — they span multiple domains
- Cost to productivity: consuming broader information is extracurricular work that often goes unrewarded
- The specialization trend (driven by technical diversity) pulls writers toward silos, away from big-picture thinking
Insights
- The “regression testing for documentation” metaphor is original and valuable: new content doesn’t just add; it can break existing user journeys
- The systems thinking approach is genuinely difficult to justify to managers: the value is invisible until something goes wrong (undocumented deprecation, conflicting terminology)
- Tom Johnson’s body of work is a rare example of applying domain-specific theory (systems thinking) to technical communication
Connections
- The inverse Conway maneuver article: Netflix’s fragmented 20-app observability problem is a concrete example of the documentation ecosystem problem at the product level
- Connects to the AI governance gambit: the “skills gap” the article identifies includes documentation literacy — people can’t use AI tools they don’t understand
- The pointillism metaphor (thousand dots that don’t resolve into a picture) applies directly to any large codebase’s documentation
Raw Excerpt
“Each new document on a developer portal is an invasive species. It introduces new terms, deprecates implied assumptions, and forks developer journeys in ways the adding team never considered. Systems thinking asks: what does this new species do to the existing ecosystem? Most teams never ask that question.”