technical-writing

name	Technical Writing
description	Creating clear, accurate, and usable documentation for technical products, APIs, and systems
license	MIT
compatibility	universal
audience	developers, technical writers, product managers
category	interdisciplinary

Technical Writing

What I Do

I transform complex technical information into clear, accurate, and usable documentation. I create user guides, API documentation, system architecture documents, and knowledge base articles that help users understand and use products effectively.

When to Use Me

• Writing API documentation and reference guides
• Creating user manuals and getting started guides
• Documenting system architecture and design decisions
• Writing release notes and changelogs
• Building internal knowledge bases
• Simplifying complex technical concepts for various audiences

Core Concepts

1. Audience Analysis: Tailoring content to reader knowledge level
2. Document Planning: Outlining and structuring for clarity
3. Plain Language: Clear, concise, jargon-free writing
4. Information Architecture: Logical grouping and navigation
5. Task-Based Documentation: How-to guides organized by user goals
6. API Documentation Standards: OpenAPI, AsyncAPI, and DocOps
7. Version Control for Docs: Git-based documentation workflows
8. Single-Source Publishing: Reusing content across formats
9. Accessibility in Docs: Structure, headings, alt text
10. Documentation Testing: Verifying code examples work

Code Examples

API Documentation Generator

class APIDocGenerator {
  constructor(options = {}) {
    this.baseUrl = options.baseUrl || '/api/v1';
    this.version = options.version || '1.0.0';
    this.endpoints = [];
  }
  
  addEndpoint(method, path, config) {
    this.endpoints.push({
      method: method.toUpperCase(),
      path: this.formatPath(path),
      summary: config.summary || '',
      description: config.description || '',
      tags: config.tags || [],
      parameters: this.extractParameters(path, config.parameters || []),
      requestBody: config.requestBody,
      responses: config.responses || {},
      examples: config.examples || []
    });
    return this;
  }
  
  formatPath(path) {
    return path.replace(/{([^}]+)}/g, );
  }
  
  () {
     pathParams = path.() || [];
     pathParamNames = pathParams.( p.(, -));
    
     [
      ...pathParamNames.( ({
        name,
        : ,
        : ,
        : { :  }
      })),
      ...parameters
    ];
  }
  
  () {
     md = ;
    md += ;
    md += ;
    
     grouped = .();
    
     ( [tag, endpoints]  .(grouped)) {
      md += ;
      
       ( endpoint  endpoints) {
        md += .(endpoint);
      }
    }
    
     md;
  }
  
  () {
     md = ;
    md += ;
    
     (endpoint.) {
      md += ;
    }
    
     (endpoint.. > ) {
      md += ;
      md += ;
      md += ;
      
      endpoint..( {
        md += ;
      });
      md += ;
    }
    
     (endpoint.. > ) {
      md += ;
      
      endpoint..( {
        md += ;
        md += ;
        md += ;
         (ex.) {
          md += ;
        }
        md += ;
        
        md += ;
        md += ;
        md += ;
        md += ;
      });
    }
    
     md;
  }
  
  () {
     {
      : ,
      : {
        : ,
        : .
      },
      : [{ : . }],
      : .()
    };
  }
  
  () {
     paths = {};
    
    ..( {
       pathKey = endpoint..(, );
      
       (!paths[pathKey]) paths[pathKey] = {};
      paths[pathKey][endpoint..()] = {
        : endpoint.,
        : endpoint.,
        : endpoint.,
        : endpoint.,
        : endpoint.,
        : endpoint.
      };
    });
    
     paths;
  }
  
  () {
     grouped = {};
    
    ..( {
       tag = endpoint.[] || ;
       (!grouped[tag]) grouped[tag] = [];
      grouped[tag].(endpoint);
    });
    
     grouped;
  }
}

Documentation Linter

class DocLinter {
  constructor() {
    this.rules = [
      { id: 'HEADING-ORDER', check: this.checkHeadingOrder.bind(this) },
      { id: 'CODE-LANGUAGE', check: this.checkCodeLanguage.bind(this) },
      { id: 'LINK-TEXT', check: this.checkLinkText.bind(this) },
      { id: 'COMPLEXITY', check: this.checkComplexity.bind(this) },
      { id: 'ACTIVE-VOICE', check: this.checkActiveVoice.bind(this) }
    ];
  }
  
  lint(content, filePath) {
    const results = [];
    const lines = content.split('\n');
    
    this.rules.forEach( => {
       issues = rule.(content, lines, filePath);
      results.(...issues);
    });
    
     {
      : filePath,
      : results,
      : .(results)
    };
  }
  
  () {
     issues = [];
     headingLevels = [];
    
    lines.( {
       match = line.();
       (match) {
         level = match[].;
         (level > headingLevels[headingLevels. - ] + ) {
          issues.({
            : index + ,
            : ,
            : ,
            : 
          });
        }
        headingLevels.(level);
      }
    });
    
     issues;
  }
  
  () {
     issues = [];
     codeBlockRegex = ;
     match;
    
     ((match = codeBlockRegex.(content)) !== ) {
       (!match[]) {
         lineNumber = content.(, match.).().;
        issues.({
          : lineNumber,
          : ,
          : ,
          : 
        });
      }
    }
    
     issues;
  }
  
  () {
     issues = [];
     sentences = content.();
     longSentences = sentences.( s.(). > );
    
     (longSentences. > sentences. * ) {
      issues.({
        : ,
        : ,
        : 
      });
    }
    
     issues;
  }
  
  () {
     issues = [];
     passivePatterns = [
      ,
      
    ];
    
    passivePatterns.( {
       matches = content.(pattern);
       (matches && matches. > ) {
        issues.({
          : ,
          : ,
          : 
        });
      }
    });
    
     issues;
  }
  
  () {
     weights = { : , : , :  };
     maxScore = ;
    
     penalty = issues.(
       sum + (weights[issue.] || ) * ,
      
    );
    
     .(, maxScore - penalty);
  }
}

Version Changelog Generator

class ChangelogGenerator {
  constructor() {
    this.commits = [];
    this.breakingChanges = [];
    this.features = [];
    this.fixes = [];
    this.chores = [];
  }
  
  addCommits(commits, options = {}) {
    const parser = new CommitParser();
    
    commits.forEach(commit => {
      const parsed = parser.parse(commit.message);
      
      if (parsed.breaking) {
        this.breakingChanges.push({ commit, parsed });
      } else if (parsed.type === 'feat') {
        this.features.push({ commit, parsed });
      } else if (parsed.type === 'fix') {
        this.fixes.push({ commit, parsed });
      } else {
        this.chores.push({ commit, parsed });
      }
    });
    
     ;
  }
  
  () {
     version = options. || .();
     date = options. ||  ().().()[];
    
     md = ;
    md += ;
    
     (.. > ) {
      md += ;
      ..( {
        md += ;
         (parsed.) {
          md += ;
        }
        md += ;
      });
      md += ;
    }
    
     (.. > ) {
      md += ;
      ..( {
        md += ;
      });
      md += ;
    }
    
     (.. > ) {
      md += ;
      ..( {
        md += ;
      });
      md += ;
    }
    
     (.. > ) {
      md += ;
      ..( {
        md += ;
      });
    }
    
     md;
  }
  
  () {
     hasBreaking = .. > ;
     hasFeatures = .. > ;
     hasFixes = .. > ;
    
     parts = [, , ];
    
     (hasBreaking) {
      parts[]++;
      parts[] = ;
      parts[] = ;
    }   (hasFeatures) {
      parts[]++;
      parts[] = ;
    }   (hasFixes) {
      parts[]++;
    }
    
     parts.();
  }
}

  {
  () {
     conventionalRegex = ;
     match = message.(conventionalRegex);
    
     (!match) {
       { : , : message, :  };
    }
    
     [, type, scope, description] = match;
     breaking = description.();
    
     breakingDescription = breaking 
      ? description.()[]?.()
      : ;
    
     {
      type,
      scope,
      : description.()[].(),
      breaking,
      breakingDescription
    };
  }
}

Best Practices

1. Know your audience and write to their level
2. Use active voice and present tense
3. Write clear, concise sentences (under 25 words)
4. Use consistent terminology throughout
5. Provide context and examples for complex concepts
6. Structure documents with clear hierarchy
7. Keep code examples working and tested
8. Use tables for structured information
9. Include troubleshooting and common errors sections
10. Review and edit documentation regularly