jonesrussell Technical Writing
Overview
Write technical content (docs, site copy, READMEs, guides) that matches Russell's voice: second person, direct, instructional. This skill covers everything that is NOT a blog post. For blog posts, use the blog-writing skill instead.
When to Use This vs blog-writing
| Content type | Skill |
|---|---|
| Blog posts (Hugo, frontmatter, Ahnii/Baamaapii) | blog-writing |
| Documentation guides, site templates, READMEs, landing pages, project descriptions | technical-writing (this skill) |
Voice Rules
| Element | Rule |
|---|---|
| Voice | Second person, direct, instructional. "You define an entity type" not "Entities are defined." Not corporate "we". |
| Concise | Short sentences. One idea per paragraph. No filler or throat-clearing. |
| Code blocks | Always specify language tag. After each block, add 1-2 sentences explaining what it does or why. |
| Links | Link first mention of products, tools, or projects. |
| Headings | H2 for main sections, H3 for subsections. Descriptive, keyword-rich. "Define Your Entity Type" not "Step 1". No "Wrapping Up" or "Conclusion". |
| Em dashes | Use sparingly and on purpose. Prefer periods (two short sentences), colons, or commas. One or two per file maximum. Zero is fine. |
What to Avoid
| Mistake | Fix |
|---|---|
| Marketing fluff ("powerful", "seamlessly", "robust", "comprehensive") | State what things DO. "Waaseyaa generates CRUD endpoints" not "Waaseyaa provides a powerful API layer." |
| Passive voice | Active, second person. "You write access policies" not "Access policies can be configured." |
| First person | No "I found", "my setup", "we built". Use "you" throughout. |
| Abstract descriptions | Concrete. "43 packages across 7 layers" not "a modular, extensible architecture." |
| Em dash overuse | Heavy "—" usage reads as AI-written. Replace with periods, colons, commas. |
| Formulaic contrast constructions | Don't keep repeating lines like "X is not Y, it is Z." If the point is clear without the contrast move, write the direct sentence. |
| Casual opposition fillers | Avoid low-value "instead of" and "rather than" phrasing when a direct sentence is clearer. Keep contrast for real tradeoffs, not connective tissue. |
| Flat cadence | Vary sentence and paragraph length. Documentation can be plain without sounding mechanically repetitive. |
| Throat-clearing intros | State what the page/section covers in one sentence. No "In this guide, we will explore..." |
| Generic headings | "Check Access in Controllers" not "Checking Access" or "How to Check Access". Use imperative form. |
| "Wrapping Up" / "Conclusion" / "Summary" sections | End naturally. No closing header needed. |
| Unexplained code blocks | After every code block, 1-2 sentences on what it does or why. |
| Time estimates in headings | Don't add reading time or duration estimates. |
Sentence Style
Before (generic/corporate):
The entity system provides a comprehensive way to manage structured content through a powerful field API.
After (correct):
The entity system is how you manage structured content. You define entity types in code, attach typed fields, and let the framework handle storage and validation.
Before (passive/abstract):
Access control can be configured through policies that are evaluated at the entity level.
After (correct):
You write access policies. The framework evaluates them at both the entity and field level. If no policy grants access, the operation is denied.
Before (em dash heavy):
Waaseyaa — an entity-first framework — rebuilds Drupal's best ideas — entities, fields, typed storage — on modern PHP.
After (correct):
Waaseyaa rebuilds Drupal's best ideas on modern PHP. Entities, fields, typed storage, access policies. No global state, no legacy baggage.
Structure Patterns
Documentation Guide
# [Descriptive Title]
[One sentence: what this guide covers.]
## [First Concept or Task]
[Short explanation.]
```language
code example
[1-2 sentences: what the code does or why.]
[Next Concept]
[Continue pattern. Short paragraphs, code, explanation.]
### Site Page / Landing Copy
[Headline] [One sentence tagline or description. No filler.]
[Section heading] [2-3 short sentences max. State what it IS, then what it DOES.]
[Section heading] [Same pattern. Direct, concrete.]
### README
Project Name
[One sentence: what it is.]
Install
command
[What the command does.]
Usage
[Show the primary use case with code.]
[Explain what the code does.]
## Cultural Context
Russell is Anishinaabe. Some project names have Anishinaabemowin origins:
- **Waaseyaa**: "it is bright" or "there is light"
- **Minoo**: "it is good"
Reference these naturally when relevant. Don't over-explain or make them performative. State the meaning once, directly.
## Checklist
Before finishing any technical writing task, verify:
- [ ] Second person throughout (no "we", "I", or passive voice)
- [ ] No more than 1-2 em dashes in the entire file
- [ ] Contrast constructions like "X is not Y, it is Z" are not repeated as a stylistic crutch
- [ ] No marketing fluff words ("powerful", "seamlessly", "robust")
- [ ] Sentence cadence varies enough that the page does not sound mechanically repetitive
- [ ] Every code block has 1-2 sentences of explanation after it
- [ ] Headings are descriptive and keyword-rich (imperative form)
- [ ] No "Wrapping Up", "Conclusion", or "Summary" section
- [ ] Short sentences. One idea per paragraph.
- [ ] First mentions of tools/projects are linked