Companion to #232.
Context
A Community feature is planned: people publish docs they are willing to show, everyone can comment underneath. Once more than a handful exist, an undifferentiated list stops working and the shelf structure has to be decided. This issue is about that structure — specifically the axis, before the label list.
The axis question: profession or topic?
Both are defensible. Recommending topic, with profession available later as a filter rather than as the shelves.
Why not profession as the primary axis. Profession answers who wrote this; topic answers what is it about. A reader browsing a community browses by interest, and the two come apart constantly — an engineer's teardown of index funds belongs on Investing, not Engineering. Filing by author's job puts it in the wrong place, and filing by "the job this doc is useful to" is just topic with extra steps.
Profession shelves are also self-excluding in a way topic shelves are not. A shelf labelled Consulting tells everyone who is not a consultant to skip it — even though a consulting-grade competitive teardown is exactly what a marketer or a founder wants to read. Business invites all three.
Profession is still useful, just not as the shelf: as author-profile metadata or a secondary facet ("show me Engineering docs written by VCs"), it adds signal without fragmenting the browse.
Proposed categories
The starting list — Productivity · Career · Engineering · Business · Investing · Health · History — is a reasonable browse taxonomy. One thing to be deliberate about: it mixes two kinds of label.
- Subject domains: Engineering, Business, Investing, Health, History
- Life topics: Productivity, Career
Content sites mix these routinely and it works, so this is not an objection. But it means some docs sit plausibly in two shelves ("how I restructured my week around deep work" is Productivity and Career), so the model needs one primary category per doc, with any others as tags. Without that rule the same doc appears twice and every shelf count becomes unreliable.
The cold-start problem
Seven shelves against early volume means most of them show one or two docs, and a category page with two items reads as abandoned — worse than no categories at all.
Rather than guessing which shelves to merge at launch, define the full list up front but only render a shelf once it has at least N docs (N=3 or 5). Everything else stays reachable under All. The taxonomy is then stable from day one, and the page never displays an empty room. Shelves light up as the community fills them, which is also a visible growth signal.
How this connects to Examples (#232)
The "editor's picks" idea and the Examples page are the same content viewed two ways, which is worth making explicit in the data model rather than maintaining twice.
A published community doc carries:
| field |
purpose |
example |
category |
its Community shelf — one, required |
Investing |
use_case |
its Examples card — optional |
Company Deep Dive |
featured |
editor's pick |
true |
Then:
- Community = every public doc, browsed by
category. Reader question: what do I want to read?
- Examples =
featured docs, grouped by use_case. Visitor question: what can I make?
Two pages, two taxonomies, one pool. The Examples cards in #232 stop being static demos and become real docs that real people wrote — which is the whole argument for that page, since a curated example written by Julie or Serena or Claire carries more weight than a synthetic sample.
Open questions
- Who can set
featured? Maintainers only, or a nomination flow?
- Is
category enforced at publish time, or inferred and then confirmable?
- Only
visibility: public docs appear, presumably — unlisted explicitly does not (per the existing access policy, unlisted is link-only and not catalog-discoverable). Worth stating so the Community query cannot regress into leaking unlisted docs.
- Moderation and takedown: who removes a doc from Community, and does that unpublish it or just unshelve it?
Companion to #232.
Context
A Community feature is planned: people publish docs they are willing to show, everyone can comment underneath. Once more than a handful exist, an undifferentiated list stops working and the shelf structure has to be decided. This issue is about that structure — specifically the axis, before the label list.
The axis question: profession or topic?
Both are defensible. Recommending topic, with profession available later as a filter rather than as the shelves.
Why not profession as the primary axis. Profession answers who wrote this; topic answers what is it about. A reader browsing a community browses by interest, and the two come apart constantly — an engineer's teardown of index funds belongs on Investing, not Engineering. Filing by author's job puts it in the wrong place, and filing by "the job this doc is useful to" is just topic with extra steps.
Profession shelves are also self-excluding in a way topic shelves are not. A shelf labelled Consulting tells everyone who is not a consultant to skip it — even though a consulting-grade competitive teardown is exactly what a marketer or a founder wants to read. Business invites all three.
Profession is still useful, just not as the shelf: as author-profile metadata or a secondary facet ("show me Engineering docs written by VCs"), it adds signal without fragmenting the browse.
Proposed categories
The starting list — Productivity · Career · Engineering · Business · Investing · Health · History — is a reasonable browse taxonomy. One thing to be deliberate about: it mixes two kinds of label.
Content sites mix these routinely and it works, so this is not an objection. But it means some docs sit plausibly in two shelves ("how I restructured my week around deep work" is Productivity and Career), so the model needs one primary category per doc, with any others as tags. Without that rule the same doc appears twice and every shelf count becomes unreliable.
The cold-start problem
Seven shelves against early volume means most of them show one or two docs, and a category page with two items reads as abandoned — worse than no categories at all.
Rather than guessing which shelves to merge at launch, define the full list up front but only render a shelf once it has at least N docs (N=3 or 5). Everything else stays reachable under All. The taxonomy is then stable from day one, and the page never displays an empty room. Shelves light up as the community fills them, which is also a visible growth signal.
How this connects to Examples (#232)
The "editor's picks" idea and the Examples page are the same content viewed two ways, which is worth making explicit in the data model rather than maintaining twice.
A published community doc carries:
categoryInvestinguse_caseCompany Deep DivefeaturedtrueThen:
category. Reader question: what do I want to read?featureddocs, grouped byuse_case. Visitor question: what can I make?Two pages, two taxonomies, one pool. The Examples cards in #232 stop being static demos and become real docs that real people wrote — which is the whole argument for that page, since a curated example written by Julie or Serena or Claire carries more weight than a synthetic sample.
Open questions
featured? Maintainers only, or a nomination flow?categoryenforced at publish time, or inferred and then confirmable?visibility: publicdocs appear, presumably —unlistedexplicitly does not (per the existing access policy, unlisted is link-only and not catalog-discoverable). Worth stating so the Community query cannot regress into leaking unlisted docs.