Gardening Philosophy

Gardening Philosophy

Lexicon is one concrete tool for the Thousand Years Garden philosophy: build environments, tools, and practices that help domain experts express their own language with increasing autonomy.

The Garden manifesto argues that sustainable futures are cultivated rather than delivered, and that diversity depends on people being able to think and work in their own terms. Lexicon applies that idea to software vocabulary.

What Lexicon Takes from Garden

Garden principle	Lexicon practice
Prefer cultivation over top-down delivery.	Treat vocabulary as a living source artifact that can be edited, versioned, composed, searched, and generated.
Protect diversity of expression.	Preserve local dialects through multiple roots, imports, type references, notes, comments, and synonyms.
Avoid colonising taxonomies.	Let each product, API, UI, analytics, support, or operations surface own its terms instead of forcing one global model.
Create affordances for experts.	Provide CLI, generated code, search, and editor completion so domain language becomes easy to contribute safely.
Make each affordance yield more affordances.	A lexicon can generate Swift, Kotlin, Go, Rust, TypeScript, JSON, JSON-LD, editor indexes, search indexes, and future tools.
Lower the cost and risk of change.	Use validation, refs, diffs, composition conflicts, and generated accessors to make vocabulary changes reviewable and testable.
Support bottom-up composability.	Import small vocabularies into larger graphs without erasing their original ownership.

The Core Fit

Garden's concern is not simply that teams use the wrong words. It is that dominant structures often make people express someone else's model instead of their own.

Lexicon is designed against that failure mode:

• API teams can name API concepts in API language.
• UI teams can preserve UI language.
• UX teams can describe journeys, actions, and tasks.
• Data teams can model persistence and analytics vocabulary.
• Support and operations teams can add their own terms.
• Shared meaning is expressed through references, not imposed by flattening every dialect into one taxonomy.

The important move is composition. A lexicon does not ask every domain to become the same domain. It gives them a way to communicate.

How This Should Shape the Wiki

The wiki should not only document commands. It should teach a way of working:

1. Start from the language people already use.
2. Keep ownership local.
3. Split files around real domain ownership.
4. Use imports to compose, not centralize.
5. Use types for shared semantics.
6. Use synonyms when two local terms genuinely mean the same thing.
7. Use notes for domain-facing explanation.
8. Use comments for authoring/tooling context.
9. Generate code so vocabulary becomes a practical affordance.
10. Use search and editor support so contributors can discover existing language before inventing disconnected terms.

The detailed pages follow that shape:

• Core Concepts explains the semantic model.
• Document Syntax keeps syntax tied to meaning.
• Composition and Imports shows how to split ownership without losing connection.
• Commerce Example demonstrates separate API, UI, session, UX, and support dialects in one composed graph.
• Editor Support makes contribution safer at authoring time.
• Code Generation turns shared language into everyday source-code affordances.

What Good Lexicon Gardening Looks Like

Good:

commerce:
	api:
		order:
			submit:
	ui:
		checkout:
			button:
				primary:
				+ commerce.api.order.submit
	analytics:
		event:
			checkout_started:
			+ commerce.ui.checkout.button.primary

This keeps API, UI, and analytics language separate while documenting their relationship.

Less good:

commerce:
	order_submit_checkout_started_primary_button_event:

This flattens several perspectives into one name. It may be convenient for one tool, but it removes the structure future contributors need.

Practical Review Questions

When reviewing a lexicon change, ask:

• Does this preserve the contributor's native domain language?
• Is a new term genuinely new, or should it reference an existing term?
• Would a synonym better preserve a local dialect?
• Is a type being used to share semantics without collapsing ownership?
• Would this be easier to garden if a subtree moved into its own file?
• Will generated code make the vocabulary easier to use, or is more editor/search support needed?
• Are notes written for domain readers and comments written for maintainers?

Workflow Guides

The philosophy becomes useful when it shapes everyday vocabulary work. Vocabulary Gardening Workflows collects the practical side: before/after refactors, domain-owner review checklists, analytics, support, semantic UI and operations examples, a decision guide for types/synonyms/imports/roots, and a proposal template.

That page should keep growing from real implementation practice. In Garden terms, the wiki itself should be cultivated from use.