markitect-main/examples/content-generator/artifacts/guidelines/authoring-rules.md

---
id: primer-authoring-rules-v1
name: AuthoringRules
artifact_type: content
description: Comprehensive guidelines for writing effective InfoTech primers
version: 1.0.0
tags:
  - guidelines
  - authoring
  - quality-standards
---

# 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

### 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

### 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

### 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

### 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

---

## 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. 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

---

## 8. 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