# Guide Writing

> Use when writing or editing guide docs — files under guide/src/

- Skill: `tomevault-io/guide-writing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/guide-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/guide-writing/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/guide-writing

---


# Guide Writing

## Overview

This skill captures the writing style of the `guide/` mdbook. Apply it when creating or modifying any file under `guide/src/`.

## Voice & Tone

- Active voice throughout; imperative for setup steps ("Create a file", "Modify `Cargo.toml`")
- No hedging: "must" not "should ideally", "returns" not "will typically return"
- Semi-formal: engineer-to-engineer, no marketing fluff, no filler transitions

## Sentence & Section Length

- Sentences: 10–25 words; split complex ideas rather than stacking clauses
- Sections: 10–40 lines; one focused idea per section

## Teaching Approach

**Code first, explanation after.** Show a working example, then extract the key point.

```rust
// Show this first, then explain what's happening
#[defun]
fn inc(x: i64) -> Result<i64> {
    Ok(x + 1)
}
```

- Progressive complexity: simple case first, advanced options after
- Explain trade-offs explicitly when presenting multiple options — don't just list them
- Call out failure modes and edge cases directly; don't gloss over them

## Structure

| Content type | Format |
|---|---|
| Reasoning / rationale | Prose |
| Options / parameters | Bullet list (one line each; prose for elaboration) |
| Setup sequences | Numbered steps or sequential bash blocks |
| Complete patterns | Fenced code block |
| Identifiers in prose | Backtick inline code |

## Audience Assumptions

- Readers know Rust **or** Emacs well — no hand-holding for either domain's fundamentals
- C FFI concepts (raw pointers, `extern`, `cdylib`) are understood
- Don't explain what `&mut`, `Box`, or `Result` mean

## Code Examples

- Substantial enough to copy-paste and run
- Include both Rust and Elisp when showing a Lisp-facing API
- Use real scenarios (e.g. wrapping a hash map, a git repo) not toy abstractions
- One good example beats several mediocre ones

## Terminology

- Precise and consistent: pick one term and use it throughout (e.g. always "type conversion", never "type casting")
- Domain terms — `defun`, `user-ptr`, `GIL`, `signal`, `throw` — used without apology or inline definition

## Common Mistakes

- Passive voice: "The type can be embedded" → "You can embed the type"
- Over-hedging: "Note that you may want to consider using..." → "Use X when Y"
- Listing options without trade-offs: always say when to prefer each
- Leaking project internals: CI matrices, supported OS counts, test version lists — omit unless directly relevant to the reader's setup

---
> Source: [ubolonton/emacs-module-rs](https://github.com/ubolonton/emacs-module-rs) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-20 -->