AGENTS.md

1# AGENTS.md - Elixir School Writing Style Guide
2 
3## Voice Overview
4 
5Elixir School's voice reads like a senior engineer talking to peers at a whiteboard: technically precise but never stuffy. We respect the reader's intelligence without assuming they know everything. We are direct and opinionated — we tell you what works and what does not, and why. The writing is warm, collaborative, and efficient. We get to the point quickly, let code do the heavy lifting, and trust the reader to keep up.
6 
7---
8 
9## Writing Style
10 
11### Core Characteristics
12 
13- **Inclusive "we" and "let's"** — The reader is a collaborator, not a student. "Let's look at a basic example", "Before we can jump into the deeper waters", "We'll cover what Release Please is and how it works".
14- **Concise scene-setting** — Each section opens with a short orienting sentence before diving in. Never more than 2-3 sentences of preamble.
15- **Show, then explain** — Code examples come first or very quickly after a concept is introduced. Explanation follows the example, not the other way around.
16- **Cross-references as breadcrumbs** — "We briefly covered guards in the Control Structures lesson", "As we saw in the Enum lesson". Links topics into a coherent curriculum or body of work.
17- **Practical framing** — Topics are motivated by real problems: "Manually updating version numbers in mix.exs, crafting changelogs... can quickly become overwhelming." Never abstract motivation.
18- **Minimal jargon without dumbing down** — Technical terms used correctly and introduced naturally. No glossary-style definitions unless truly needed. If something has a prerequisite, say so and link to it.
19- **Short paragraphs** — Rarely more than 3-4 sentences. Dense information gets bullet points or code blocks, not walls of text.
20- **Rhetorical questions as transitions** — "What if we could automate all of that while also improving your development workflow?" Used sparingly, always followed by the answer.
21- **Confident but not preachy** — States best practices directly: "Each commit should represent one logical change." No hedging with "you might want to consider possibly..."
22- **Light personality leaks through** — "Automagically generate a changelog", "Gone are the days of wondering and debating". Not dry, but humor is restrained and natural.
23- **Genuine enthusiasm** — When we are excited about a tool or approach, it comes through: "We're excited about all the new possibilities and content in store and we hope you are too!"
24 
25### Sentence Structure Patterns
26- Compound sentences joined by "and" or "but" rather than semicolons
27- Dashes for asides — like this — rather than parentheses
28- Active voice almost exclusively
29- Imperative mood for instructions: "Create .github/workflows/release-please.yml"
30- Present tense for describing behavior: "Release Please maintains Release PRs that are kept up-to-date"
31- Contractions always ("we'll", "you're", "it's", "don't") — never "we will" or "do not" unless for deliberate emphasis
32 
33### What We Do NOT Do
34- Use profanity in published writing
35- Write extended personal anecdotes or memoir-style digressions
36- Use emoji
37- Use slang or overly casual language
38- Use phrases like "In today's fast-paced world" or "Let's dive deep into"
39- Use buzzwords: "leverage synergies", "paradigm shift", "best-in-class"
40- Pad with filler sentences that convey no information
41- Write overly long introductions before getting to the point
42- Use passive voice when active voice works
43- Use "utilize" when "use" works fine
44- Write "please note that" or "it's important to note that" — just states the thing
45- Say "I hope this helps", "Happy coding!", or similar platitudes
46- Say "lol"
47- Use ALL CAPS for emphasis
48- Over-explain things the reader should already know at their level
49 
50---
51 
52## Universal Rules
53 
54### ALWAYS:
55- Leads with the practical problem before introducing the solution
56- Uses code examples liberally — real code, not pseudocode
57- Gives credit — links to tools, projects, and people by name
58- Provides escape hatches — "be sure to check out the documentation for the complete list of options"
59- Ends with forward momentum — what is next, what to try, what to watch for
60- Uses the Oxford comma
61- Is concrete over abstract — specific tools, real error messages, actual commands. Never "consider using a CI/CD tool" when we mean "use GitHub Actions."
62 
63### Vocabulary Fingerprints
64- "Let's look at..." / "Let's explore..."
65- "Enter [tool/concept]" as an introduction
66- "The real power of..." / "The real difference is..."
67- "Whether you're a [X] or [Y]..."
68- "Without further ado"
69- "Pro tip:"
70- Ending clauses with "...and that's [not] a bad thing"
71- "We know from experience..."
72- "If you're familiar with [X], [Y] is [comparison]"
73 
74---
75 
76## Formatting Preferences
77 
78- **Headers**: H2 for major sections, H3 for subsections. Never H1 within body content (reserved for title).
79- **Code blocks**: Always include language identifier. Real, runnable examples preferred.
80- **Links**: Inline markdown links with descriptive text, never "click here."
81- **Bold**: For key terms on first introduction or for emphasis in lists. Never for entire sentences.
82- **Italics**: For asides, book/movie titles, or gentle emphasis.
83- **Horizontal rules** (---): Before closing/signature sections only.
84 
85---
86 
87## Content Architecture
88 
89### Lessons / Tutorials:
901. One-sentence overview of what you will learn
912. Brief context/motivation (2-3 sentences max)
923. Core content with code examples
934. Connections to related topics
945. Invitation to contribute or ask questions
95 
96### Blog Posts / Articles:
971. Brief hook — the problem or opportunity
982. Context — why this matters now, what changed
993. The meat — walkthrough with code, configuration, or process
1004. Broader implications or additional use cases
1015. Closing — forward-looking summary, invitation for engagement
102 
103---
104 
105## Tone Calibration
106 
107| Situation | Tone |
108|-----------|------|
109| Explaining a concept to a beginner | Warm, patient, collaborative ("we") |
110| Introducing a tool or workflow | Enthusiastic, practical, honest about limitations |
111| Recommending a practice | Direct and confident, backed by experience |
112| Discussing trade-offs | Fair and balanced, concrete about pros and cons |
113| Discussing the future / roadmap | Optimistic and genuinely excited |
114| Wrapping up | Concise, forward-looking, inviting engagement |
115