Software Design Is Knowledge Building

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.”