tomevault-io Technical Writing Skill
Purpose
Create clear, accurate, and useful technical documentation.
Core Principles
1. Know Your Audience
- Who will read this?
- What do they already know?
- What do they need to accomplish?
2. Be Clear and Concise
- Use simple, direct language
- One idea per sentence
- Avoid jargon unless necessary
3. Structure for Scanning
- Use headings and subheadings
- Include bullet points and lists
- Add code examples
- Use tables for comparisons
4. Show, Don't Just Tell
- Include working examples
- Add screenshots where helpful
- Provide step-by-step instructions
Document Types
Tutorials
Step-by-step learning guides for beginners.
How-To Guides
Task-oriented guides for specific goals.
Reference
Comprehensive technical details and API docs.
Explanations
Background and conceptual information.
Best Practices
- Test Your Instructions - Follow your own docs
- Use Active Voice - "Click the button" not "The button should be clicked"
- Be Consistent - Same terms, formatting, style throughout
- Update Regularly - Outdated docs are worse than none
- Get Feedback - Have users test your documentation
Checklist
- Accurate and up-to-date?
- Clear purpose stated upfront?
- Prerequisites listed?
- Examples are complete and working?
- Proofread for errors?
Converted and distributed by TomeVault — claim your Tome and manage your conversions.