Tech Writer

Mode Selection

User arguments determine the mode:

• "create" or "guide": Use Creation Workflow (Default for "study guide" requests).
• "update" or "maintain": Use Update Workflow (Default for "update docs" requests).
• "edit" or "refine": Apply Style Rules to existing text.

Creation Workflow (Study Guides)

Goal: Create high-quality technical reference guides and cheat sheets from raw content. Focuses on engineering best practices, visual retention (tables, emojis, formulas), and concise summaries.

1. Analyze & Distill

Identify core concepts. Ask: "How would I explain this to another engineer in 30 seconds?"

• Definitions: Convert text definitions into "Equations" (e.g., Agent = LLM + Tools).
• Components: Assign distinct emojis to key components (e.g., 🧠 Brain, 🛠️ Tool).
• Comparisons: Always look for "X vs Y" opportunities for tables.

2. Standard Structure (The "Cheat Sheet" Pattern)

1. Fundamental Concept: Simple definition, Equation/Formula.
2. Architecture/Components: List of parts with emojis and brief roles.
3. Comparative Analysis: Table comparing Traditional vs New approach.
4. Engineering/Implementation: Code snippets, pseudo-code, or practical constraints.
5. Key Takeaways/Rules: "Golden Rules" or best practices.

3. Formatting Standards

• Math/Formulas: Use Latex syntax ($$) for conceptual formulas.
• Tables: Mandatory for any comparison.
• Callouts: Use blockquotes (>) for critical rules or "Scenario" examples.
• Language: Default to Portuguese (pt-BR) unless requested otherwise.

4. Copyright & Code Examples

CRITICAL: When including code examples in documentation:

• ✅ DO: Create original, educational, generic implementations
• ✅ DO: Write reusable patterns and abstractions
• ✅ DO: Focus on demonstrating concepts, not production code
• ✅ DO: Use simple, clear variable/function names
• ❌ DON'T: Copy specific implementations from libraries or tutorials
• ❌ DON'T: Include business-specific or proprietary logic
• ❌ DON'T: Reproduce copyrighted code patterns verbatim

Example Approach:

# ❌ BAD: Specific implementation tied to one use case
def generate_data_analysis_script():
    # ...very specific prompts and logic...

# ✅ GOOD: Generic, reusable pattern
def chain_with_validation(
    prompts: list[str],
    validators: list[Callable],
    llm_call: Callable
) -> str:
    """Generic prompt chaining with validation."""
    # ...abstract pattern...

Update Workflow (Local Changes)

Goal: Ensure all code changes are properly documented with clear, maintainable documentation that helps users accomplish real tasks.

1. Preparation & Discovery

• Action: Check git status and untracked files.
• Read: Project config (package.json, pyproject.toml) and root README.md.
• Inventory: Locate docs/ folder and README.md files.

2. Analysis

• Structure Analysis: Map existing docs.
• Impact Analysis: For each changed file, determine:
  • New/modified public APIs?
  • Configuration changes?
  • New features?
• Filtering: Ignore changes that don't need docs (internal refactors, tests).

3. Execution (Writing)

• Simple Changes (1-2 files):
  • Write directly following Style Rules.
  • Update adjacent README.md or JSDoc.
• Complex Changes (3+ files):
  • Plan updates for API docs, User Guides, and Index files.
  • Check for "Index Documents" that need updates (e.g., SUMMARY.md, docs/index.md).
• See Reference: references/update-workflow.md for full multi-agent orchestration details (if applicable).

Style Rules (Strunk & White)

Reference: See references/style-guide.md for the complete ruleset.

Core Principles

1. Active Voice: "The system processes the request" (Good) vs "The request is processed by the system" (Bad).
2. Positive Form: "The system ignores invalid input" (Good) vs "The system does not process invalid input" (Bad).
3. Omit Needless Words: "This features helps to..." -> "This feature..."
4. Specific Language: "Handle errors appropriately" -> "Retry 3 times on 503 errors".

Documentation Philosophy

• User-Centric: Document tasks, not just implementation.
• Justify Existence: Every doc must have a clear purpose.
• No Duplication: Don't repeat what code/comments already say.

Resources

• Style Guide: references/style-guide.md
• Update Workflow: references/update-workflow.md