Skip to content

Commit ed9b6f9

Browse files
committed
feat: Add 'What is NOT a Semantic Anchor?' section to About page
- Add counter-examples table (TLDR, ELI5, etc.) - Add comparison: Good vs. Bad examples - Add testing methodology for potential anchors - Clarify the key difference between anchors and instructions Helps users understand quality criteria through negative examples.
1 parent 4bef2a2 commit ed9b6f9

1 file changed

Lines changed: 117 additions & 0 deletions

File tree

docs/about.adoc

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,123 @@ Can be *traced to key proponents, publications, or documented standards*.
7676

7777
❌ "Best practices" (no specific source)
7878

79+
== What is NOT a Semantic Anchor?
80+
81+
Not every well-known term qualifies as a semantic anchor. Understanding what *doesn't* work helps clarify what does.
82+
83+
=== Common Counter-Examples
84+
85+
These terms are frequently used but *lack the depth and definition* required for semantic anchors:
86+
87+
[cols="1,2", options="header"]
88+
|===
89+
|❌ Not a Semantic Anchor |Why Not?
90+
91+
|*"TLDR"*
92+
|Underspecified instruction with no defined structure or methodology. Just means "be brief" without any framework for how.
93+
94+
|*"ELI5"* (Explain Like I'm 5)
95+
|Vague target level with no pedagogical framework. What does "5-year-old level" mean technically? No consistent interpretation.
96+
97+
|*"Keep it short"*
98+
|Pure directive with no conceptual depth. It's an instruction, not a methodology.
99+
100+
|*"Best practices"*
101+
|Too vague and not attributable. Whose best practices? Based on what research or authority?
102+
103+
|*"Modern approach"*
104+
|Ambiguous and inconsistent. "Modern" means different things to different people and changes over time.
105+
106+
|*"Make it simple"*
107+
|No reference to specific simplification frameworks (unlike KISS principle or Occam's Razor which *are* semantic anchors).
108+
|===
109+
110+
=== Comparison: Good vs. Bad
111+
112+
[%collapsible]
113+
====
114+
*Example 1: Testing Instructions*
115+
116+
❌ *Bad*: "Write good tests"
117+
[horizontal]
118+
Problem:: Vague instruction, no methodology
119+
Result:: Inconsistent interpretations
120+
121+
✅ *Good*: "Test-Driven Development, London School"
122+
[horizontal]
123+
Activates:: Mock-heavy testing, outside-in design, interaction-based verification
124+
Proponents:: Steve Freeman, Nat Pryce
125+
Result:: Consistent, rich implementation
126+
127+
---
128+
129+
*Example 2: Communication Style*
130+
131+
❌ *Bad*: "Keep it short"
132+
[horizontal]
133+
Problem:: No structure, just a preference
134+
Result:: Arbitrary length decisions
135+
136+
✅ *Good*: "Pyramid Principle"
137+
[horizontal]
138+
Activates:: Start with conclusion, group ideas, logical ordering
139+
Proponent:: Barbara Minto
140+
Result:: Structured, repeatable communication pattern
141+
142+
---
143+
144+
*Example 3: Code Quality*
145+
146+
❌ *Bad*: "Best practices"
147+
[horizontal]
148+
Problem:: Not attributable, no specific practices
149+
Result:: Everyone has different "best practices"
150+
151+
✅ *Good*: "SOLID Principles"
152+
[horizontal]
153+
Activates:: Five specific design principles (SRP, OCP, LSP, ISP, DIP)
154+
Proponents:: Robert C. Martin
155+
Result:: Concrete, testable guidelines
156+
====
157+
158+
=== The Key Difference
159+
160+
[sidebar]
161+
****
162+
*Semantic Anchors* activate **rich, interconnected knowledge domains** from the LLM's training data.
163+
164+
*Simple Instructions* just tell the LLM **what to do**, without providing conceptual framework or methodology.
165+
****
166+
167+
Think of semantic anchors as *nouns* (methodologies, frameworks, principles) rather than *verbs* (instructions, directives).
168+
169+
=== Testing a Potential Anchor
170+
171+
Before proposing a new semantic anchor, ask an LLM:
172+
173+
[source]
174+
----
175+
What concepts do you associate with '<your term>'?
176+
----
177+
178+
If the response includes:
179+
180+
* ✅ Multiple interconnected concepts
181+
* ✅ Key proponents or publications
182+
* ✅ Specific techniques or practices
183+
* ✅ Clear scope and boundaries
184+
185+
→ It's likely a good semantic anchor!
186+
187+
If the response is:
188+
189+
* ❌ Just a simple definition
190+
* ❌ No attributed source
191+
* ❌ Vague or inconsistent interpretations
192+
* ❌ Just instructions without depth
193+
194+
→ It's probably not a semantic anchor.
195+
79196
== How to Use This Catalog
80197

81198
=== Browse by Category

0 commit comments

Comments
 (0)