Technical Writing Guide

Clarity
• Use simple, direct language
• Avoid jargon unless necessary
• Define technical terms on first use
• One idea per sentence

Conciseness
• Remove unnecessary words
• Use active voice
• Avoid redundancy
• Get to the point quickly

Consistency
• Use same terms throughout
• Follow style guide
• Maintain consistent formatting
• Use parallel structure in lists

README structure
1. Project Title & Description
2. Table of Contents
3. Installation Instructions
4. Usage Examples
5. API Documentation
6. Contributing Guidelines
7. License Information

Tutorial structure
1. What you will learn (Overview)
2. Prerequisites
3. Step-by-step instructions
4. Code examples
5. Common pitfalls
6. Next steps

API documentation
1. Endpoint description
2. HTTP method and URL
3. Parameters
4. Request example
5. Response example
6. Error codes

Function documentation
/**
 * Calculates the sum of two numbers
 * 
 * @param {number} a - First number
 * @param {number} b - Second number
 * @returns {number} Sum of a and b
 * @example
 * add(2, 3) // returns 5
 */
function add(a, b) {
  return a + b;
}

Inline comments
// Good: Explains WHY
// Cache result to avoid expensive recalculation

// Bad: Explains WHAT (code already shows this)
// Increment counter by 1

Best practices
• Show complete, working examples
• Include necessary imports
• Add comments for clarity
• Show expected output
• Progress from simple to complex

Good example
```javascript
// Import the required module
import { useState } from react;

// Create a simple counter component
function Counter() {
  const [count, setCount] = useState(0);
  
  return (
     onClick={() => setCount(count + 1)}>
      Count: {count}
    
  );
}
```

Output:
// Displays: Count: 0 (increments on click)

Active vs Passive voice
✓ Active: Click the button to submit
✗ Passive: The button should be clicked

Second person
✓ You can install the package...
✗ One can install the package...

Present tense
✓ The function returns a value
✗ The function will return a value

Commands
✓ Run npm install
✗ You should run npm install

Lists
• Use bullets for unordered items
• Use numbers for sequential steps
• Keep items parallel in structure
• Start with action verbs

Code formatting
• Use backticks for inline code
• Use code blocks for multi-line code
• Specify language for syntax highlighting
• Format consistently

Emphasis
**Bold** for important terms
*Italic* for emphasis
`Code` for technical terms

Headers
• Use consistent hierarchy
• Make headers descriptive
• Do not skip levels (H1 to H3)

Avoid
✗ Assuming knowledge
✗ Using ambiguous pronouns (it, this, that)
✗ Long, complex sentences
✗ Outdated screenshots or examples
✗ Missing error handling in examples

Do
✓ Define prerequisites
✓ Use specific nouns
✓ Break into shorter sentences
✓ Update documentation regularly
✓ Show error handling

Markdown editors
• Typora - WYSIWYG editor
• VS Code - with Markdown extensions
• Obsidian - knowledge base

Documentation generators
• JSDoc - JavaScript
• Sphinx - Python
• Javadoc - Java
• Swagger/OpenAPI - REST APIs

Style guides
• Google Developer Documentation Style Guide
• Microsoft Writing Style Guide
• Apple Style Guide

Grammar tools
• Grammarly - grammar & style
• Hemingway Editor - readability