markitect-main/examples/content-generator/prepdr/AuthoringRules.md

AuthoringRules

*How to write effective primers*

## Primer Authoring Rules

**Status:** Draft
**Intended Audience:** Human authors and AI systems generating or validating primers
**Purpose:** Ensure primers are precise, stable, and suitable as shared context for humans and AI agents

---

## 1. What a Primer Is (Normative)

An **InfoTechPrimer** is a **short, structured reference document** that establishes a **shared understanding** of a specific IT term, standard, method, or concept.

A primer:

* Defines **what the topic is**
* Explains **where it fits**
* Clarifies **scope boundaries**
* Points to **authoritative sources**

A primer does **not**:

* Teach step-by-step usage
* Advocate tools or vendors
* Explore implementation details beyond what is normatively defined

---

## 2. Target Audience

Primers are written for:

* Humans with solid general IT knowledge
* Readers who are *not specialists* in the specific topic
* AI systems that consume structured context for reasoning and coding

Authors must assume:

* Conceptual literacy
* Familiarity with basic IT terminology
* No prior deep knowledge of the topic

---

## 3. Required Structure (Mandatory)

Every primer **MUST** contain the following sections **in this order**:

1. **Definition**
2. **Context**
3. **Core Concepts**
4. **Scope and Non-Scope**
5. **Practical Implications**
6. **Formal Standards and Authoritative Sources**
7. **Related Concepts**

No section may be omitted.
Empty sections are not allowed.

---

## 4. Section Authoring Rules

### 4.1 Definition

**Purpose:** Establish an unambiguous baseline meaning.

Rules:

* 2–4 sentences maximum
* Declarative, precise language
* No metaphors, examples, or analogies
* No historical narrative

Good:

> “OAuth 2.0 is an authorization framework that enables a third-party application to obtain limited access to an HTTP service on behalf of a resource owner.”

Bad:

> “OAuth is basically a way to let apps log in without sharing passwords.”

---

### 4.2 Context

**Purpose:** Position the concept within the IT landscape.

Rules:

* Describe the domain(s) the concept belongs to
* Explain *why it exists*, not *how to use it*
* Historical notes allowed only if they clarify intent or constraints

Include:

* Typical environments
* Architectural level (protocol, pattern, framework, etc.)

---

### 4.3 Core Concepts

**Purpose:** Identify the irreducible ideas that define the topic.

Rules:

* Bullet points only
* Each bullet describes one concept
* No nested lists
* Avoid redundancy with Definition

Think: *“What must be true for this concept to exist?”*

---

### 4.4 Scope and Non-Scope

**Purpose:** Prevent conceptual drift and misuse.

Rules:

* Explicitly list inclusions and exclusions
* Use parallel structure
* Address common misconceptions

Format:

```markdown
**In Scope**
- ...

**Out of Scope**
- ...
```

This section is **critical** for AI agent correctness.

---

### 4.5 Practical Implications

**Purpose:** Describe consequences of adopting or interacting with the concept.

Rules:

* Focus on effects, not instructions
* No step-by-step guidance
* Include tradeoffs where relevant

Examples of acceptable content:

* Design constraints
* Operational complexity
* Security or scalability implications

---

### 4.6 Formal Standards and Authoritative Sources

**Purpose:** Anchor the primer in canonical truth.

Rules:

* Prefer primary sources
* Include direct links
* Avoid blogs unless widely recognized and necessary

Acceptable sources:

* RFCs
* W3C Recommendations
* ISO / IEC standards
* NIST publications
* Official specifications
* Foundational academic papers

At least **one** authoritative source is required.

---

### 4.7 Related Concepts

**Purpose:** Enable semantic navigation.

Rules:

* Short descriptions only (one line per concept)
* No deep explanations
* Avoid circular definitions

Example:

> **OpenID Connect** – An identity layer built on top of OAuth 2.0.

---

## 5. Language and Style Rules

Mandatory:

* Present tense
* Declarative sentences
* Neutral, technical tone

Avoid:

* First-person language (“we”, “you”)
* Rhetorical questions
* Marketing language
* Informal phrasing
* Emojis

---

## 6. Length Constraints

A primer should typically be:

* **600–1,000 words total**
* Short enough to be read in one sitting
* Long enough to define boundaries clearly

Exceeding this range requires justification.

---

## 7. Stability and Versioning

Primers are intended to be **stable reference artifacts**.

Rules:

* Do not chase trends
* Avoid speculative content
* Update only when:

  * Standards change
  * Definitions evolve materially
  * Authoritative sources are superseded

When updating:

* Preserve conceptual continuity
* Avoid rewriting without necessity

---

## 8. AI Optimization Rules (Explicit)

Authors **SHOULD**:

* Use consistent terminology
* Avoid synonyms for core terms once defined
* Prefer explicit over implicit assumptions
* State constraints clearly

Authors **MUST NOT**:

* Rely on context outside the document
* Assume tool- or framework-specific defaults
* Leave ambiguity where standards are explicit

---

## 9. Validation Criteria (Checklist)

A primer is valid if:

* [ ] All required sections are present
* [ ] Definition is precise and unambiguous
* [ ] Scope boundaries are explicit
* [ ] At least one authoritative source is linked
* [ ] No tutorial or marketing content exists
* [ ] Language follows declarative style rules

---

## 10. Non-Goals

InfoTechPrimers are **not**:

* Documentation replacements
* Training material
* Opinionated best-practice guides
* Tool comparisons

Those belong elsewhere.

---

### Version Note

This is **Primer Authoring Rules v0.1**.
Expect tightening, not loosening, as real primers are written and validated.



xxx