The notes on this site are organized around four subjects: Principles, Product & Design, Engineering, and Business. The categories give readers a starting point. They do not tell the whole story of why a decision matters.
One place for each kind of information
Each article is an MDX file in src/content/notes/. Its title, date, category, and author live beside the text. The names and descriptions of the categories live in src/helpers/noteCategories.ts.
For example, Seven Principles for Simple Software declares its category as principles. The category page, its label in the archive, and the navigation count all use that same classification.
This makes a small rule visible in the source: an article declares what it is about; shared metadata defines what the category means. A page does not need to invent a separate label.
Give first-time readers a starting point
How we think has a short reading selection before the full archive. It introduces maintenance responsibility, our approach to AI, and this note about the site itself.
The selection is explicit in src/helpers/thoughtsReading.ts. The archive still sorts by publication date. The two serve different purposes: one introduces a point of view; the other helps readers find a particular piece.
Keep the content accessible outside the layout
The article text is also available as Markdown, and new entries appear in the RSS feed. These are other ways to read the same content, without depending on the site’s presentation.
English and Chinese articles have separate text files. They can express the same idea in the language that reads naturally to their audience.
What this structure cannot do
Categories are a coarse guide. A decision about an AI feature might concern product design, engineering, and responsibility at once. A single category cannot express all of that.
More importantly, a tidy archive cannot make an unsupported claim credible. A useful note still needs a clear question, an explanation of the tradeoff, and enough detail for someone else to assess it. That is the standard we want these notes to meet.
Related Thoughts
Continue through the same thinking system.