Software Design Is Knowledge Building
Software design is framed as a process of building and preserving organizational knowledge, not just producing code, which explains why systems often fail when handed from a lone expert to a new team. Commenters emphasize that the real asset is the mental model of the domain and system behavior—something code, tests, and even “self-documenting” styles only partially capture—so lack of documentation, poor requirements gathering, and constant team churn make maintenance and rewrites risky and expensive. There is broad agreement that organizations underestimate the long‑term cost of owning services and the effort required for knowledge transfer, with some seeing LLMs and better documentation practices as partial aids but no substitute for sustained human understanding.
Overall reception
- Many commenters find the piece accurate and resonant with real projects, especially the idea that software design’s main output is shared understanding, not just code.
- Some think the concrete “revive vs rewrite” example is overstated: a competent team could rebuild a modest system in under a year, which is a small cost at company scale.
- Others argue that such “dead systems” are common, and the essay captures why they are so hard to revive.
Design as knowledge / mental models
- Strong agreement that the core asset is the mental model that links domain → system behavior, not the code itself.
- Brook’s Law is cited as a consequence: new people are slow until they internalize that model.
- A system becomes “dead” when no one can meaningfully change it, even if it still runs and makes money.
Simplicity vs documentation
- Several argue that aggressively simple, clear code can enable smooth handoffs with very little documentation.
- A large opposing camp insists documentation is indispensable, especially for “why” decisions, assumptions, and history; “self-documenting code” is seen as a myth.
- Suggested practices: brief module/class headers, architecture decision records, PR/ticket context, tests as behavioral documentation.
- Disagreement over professionalism: some call skipping hard documentation “unprofessional,” others see avoiding unnecessary hard work as pragmatic.
Legacy systems, rewrites, and TCO
- Multiple stories of inheriting opaque systems: teams often wrap or reimplement rather than deeply understand them, leading to layers of indirection and duplication.
- Mixed experiences: in some cases rewrites underperform the original; in others, reviving old code succeeds when driven by strong engineers.
- Many note organizations badly underestimate total cost of ownership and maintenance, especially for non-core internal services and “unwanted children” nobody wants to own.
- Build-vs-buy is revisited: internal clones of SaaS often look cheaper short term but create long-term liabilities.
Requirements and domain knowledge
- Several stress that real engineering starts with requirements and domain understanding; many developers “don’t care until coding,” leading to poor systems.
- Requirements gathering is described as mutual discovery with stakeholders; ignoring it produces shallow or misaligned designs.
Knowledge sharing, tools, and LLMs
- Knowledge hoarding is reported as common; incentives rarely reward documentation or sharing.
- Existing tools (wikis, trackers) are viewed as clumsy; search is poor and content decays.
- Some see LLMs as promising for synthesizing and querying existing knowledge bases; skeptics argue they still lack the deep, contextual understanding the article says is essential and risk generating misleading “fake understanding.”