❌ "This implements category theory functors with natural transformations..." ✅ "This function takes a list of processors and returns the one with highest confidence."

Exception: When mathematical concepts genuinely clarify the design: ✅ "Each probe is a function from system state to fragment. Probes compose like mathematical functions—you can chain them without side effects."

Why: Readers can verify concrete code behavior. Theoretical claims require specialized knowledge to evaluate, but well-chosen mathematical analogies can illuminate structure.

2. Problems Before Solutions

❌ "We need a composable stream-based meta-architecture..." ✅ "When parsing user input, we need to handle cases where the input is ambiguous or incomplete..."

Why: Problems motivate solutions. Starting with solutions makes readers wonder "why do I need this?"

3. Testable Claims Only

❌ "This system naturally emerges intelligent behavior..." ✅ "This system processes 1000 text fragments per second with 95% accuracy on our test corpus."

Why: Testable claims can be verified or refuted. Vague claims cannot be evaluated.

4. Concrete Before Abstract

❌ "Agents are pure functions plus state plus emotion..." ✅ "A text classifier that maintains accuracy statistics and adjusts confidence based on input length..."

Nuance: Abstract concepts can help after concrete examples are established: ✅ "This text classifier (shown above) follows a common pattern: observe, decide, act. This pattern appears throughout the system."

Why: Concrete examples make abstract concepts understandable. Abstractions without examples are just jargon, but patterns become visible once you have working examples.

Language Guidelines

Precision Over Poetry

Avoid:

"Emergent cognitive mesh"
"Meta-architectural primer"
"Future-proof composable"
"Bias-free implementation"

Use:

"Text processing system"
"Architecture documentation"
"Extensible design"
"Minimal dependencies"

Mathematical language when it clarifies:

"Composition" instead of "chaining things together in complex ways"
"Identity function" instead of "passthrough that doesn't change anything"
"Morphism" when you genuinely mean structure-preserving transformation

Active Voice, Specific Subjects

❌ "Streams can be chained and filtered for composable processing..." ✅ "The LazyProcessor.chain() method connects two processors in sequence."

❌ "Critics are applied when coherence drops below threshold..." ✅ "The system runs validation functions when confidence falls below 0.5."

Quantify When Possible

❌ "Low confidence triggers fallback behavior" ✅ "Confidence below 0.7 triggers the fallback processor"

❌ "Handles large volumes efficiently" ✅ "Processes 10,000 items/second using 50MB RAM"

When Mathematical Concepts Help

Good Uses of Category Theory Language

Identity preservation: ✅ "Each device keeps the same identifier across reboots. This identity persistence lets us track relationships reliably."

Composition: ✅ "Probes compose cleanly—running probe A then probe B gives the same result as a single probe that does both operations."

Functorial relationships: ✅ "The mapping from block devices to mount points preserves the containment structure—if device A contains B, then mount(A) contains mount(B)."

Bad Uses

❌ "We leverage categorical semantics to enable functorial composition across typed morphisms..." ✅ "We use mathematical composition rules to ensure operations combine predictably."

The Test: Does It Clarify Structure?

Ask yourself:

Would "function composition" be clearer than "chaining operations"?
Does "identity preservation" explain something "stable IDs" doesn't?
Does "morphism" add meaning beyond "structure-preserving function"?

If yes, use the mathematical term but define it concretely.

Document Structure

1. Start With "What" and "Why"

# Text Fragment Processor

This system parses user input into structured data types, handling 
ambiguous cases gracefully. It solves the problem of processing 
mixed-format text where traditional parsers would fail.

2. Show Core Interface Early

// Core interface - everything else builds on this
pub fn process(input: &str) -> ProcessingResult<Fragment> {
    // ...
}

3. Build Complexity Incrementally

Basic functionality
Error handling
Performance optimization
Extension points
Mathematical structure (if it helps with extension points)

4. Include Working Examples

Every major component should have a complete, runnable example.

5. Mathematical Insights (When Relevant)

After showing concrete examples, mathematical structure can illuminate:

Why extension patterns work
What invariants the system maintains
How components compose safely

6. End With Honest Limitations

What doesn't work yet
Known performance bottlenecks
Areas needing improvement

Introducing Mathematical Concepts

The Ladder Approach

Step 1: Concrete behavior

fn transform_text(input: &str) -> Result<Output> { ... }
fn transform_data(input: &Data) -> Result<Output> { ... }

Step 2: Pattern recognition "Both functions follow the same pattern: take input of one type, return output of another type, preserve certain properties."

Step 3: Mathematical insight "This is function composition—you can chain these transforms because the output type of one matches the input type of the next."

Step 4: Practical benefit "This composition property lets you build complex processors from simple ones, and guarantees they'll work together correctly."

Good Mathematical Analogies

Identity: "Like how multiplying by 1 doesn't change a number, passing data through an identity function doesn't change it."

Composition: "Like how (f ∘ g)(x) = f(g(x)) in math, processor composition applies operations in sequence."

Functors: "Like how map() preserves the shape of a list while changing its contents, our probe system preserves device relationships while changing representations."

Common Anti-Patterns to Avoid

1. The "Universal Solution"

❌ "This architecture can handle any conceivable AI workload..." ✅ "This architecture handles text classification with extensibility for similar pattern-matching tasks."

2. The "Revolutionary Breakthrough"

❌ "By combining category theory with emotional AI, we've solved artificial intelligence..." ✅ "By using composition principles from mathematics, we've made the system easier to extend and debug."

3. Mathematical Intimidation

❌ "Leveraging advanced categorical semantics and topos-theoretic foundations..." ✅ "Using function composition and type preservation to ensure reliability."

4. The "Academic Name-Drop"

❌ "Based on Minsky's Society of Mind and Lawvere's elementary topoi..." ✅ "Inspired by multi-agent systems where independent components coordinate through message passing..."

Exception: When the citation genuinely helps: ✅ "This follows the composition pattern from category theory, where operations chain predictably (see Awodey's 'Category Theory' for mathematical details)."

5. The "Future Perfect"

❌ "When fully realized, this will enable emergent artificial general intelligence..." ✅ "The next version will add parallel processing and persistent state."

Balancing Rigor and Accessibility

For Expert Audiences

Mathematical terminology is fine if defined
Can reference advanced concepts with proper citations
Assume familiarity with composition, functors, etc.

For Mixed Audiences

Introduce mathematical concepts gradually
Always provide concrete examples first
Use mathematical language to clarify, not to impress

For Beginner Audiences

Focus on code and examples
Use mathematical analogies sparingly
When you do use them, explain thoroughly

Testing Your Writing

Before publishing, ask:

Can I implement this? If not, you're missing concrete details.
Can I test this? If not, your claims are too vague.
Can I extend this? If not, you haven't shown the abstractions clearly.
Would I use this? If not, you haven't motivated the problem.
Does the math help? If mathematical language doesn't clarify structure or enable better reasoning, remove it.

Examples of Good vs. Bad

Bad Introduction

"This meta-architectural primer explores emergent cognitive mesh implementations through zero-dependency Rust primitives, establishing a bias-free foundation for future-proof composable agent societies grounded in category-theoretic morphisms and Minsky-inspired emotional heuristics."

Good Introduction

"This document describes a text processing system built in Rust without external dependencies. The system handles ambiguous inputs by running multiple parsers in parallel and selecting results based on confidence scores. It's designed for applications that need reliable text parsing with graceful degradation."

Bad Mathematical Language

"The morphism represents a typed transformation between categorical objects, enabling compositional reasoning about stream transformations through functorial mappings."

Good Mathematical Language

"Each transform function preserves the structure of its input while changing the content—like how map() preserves array length while changing elements. This structure preservation means transforms compose predictably: transform A followed by transform B always works if their types align."

When Category Theory Actually Helps

System topology example:

"Device relationships form a mathematical structure where connections between physical devices map consistently to connections between logical devices. This structure preservation (called a functor in mathematics) means that discovering new physical connections automatically reveals logical connections."

This works because:

It explains a concrete property of the system
The mathematical concept clarifies why the system behaves reliably
Readers can verify the claim by testing the system

The Key Balance

Good technical writing helps readers understand and use your system. Mathematical concepts should serve this goal, not replace it. Use mathematical language when it genuinely clarifies structure, enables better reasoning, or helps readers extend your work. Avoid it when it's just sophisticated-sounding jargon.

The test is simple: after reading your mathematical explanation, can someone build something better?