Guide Writing

• 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

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