technical-writing

name	technical-writing
description	Creating clear, comprehensive technical documentation
category	interdisciplinary
difficulty	intermediate
tags	["documentation","writing","technical","api"]
author	OpenCode Community
version	1
last_updated	2024-01-15T00:00:00.000Z

Technical Writing

What I Do

I am Technical Writing, the practice of creating clear, accurate, and accessible documentation for technical products and processes. I translate complex technical information into language that users can understand and apply. I encompass various document types: API documentation, user guides, release notes, tutorials, and system documentation. I follow established standards and style guides to ensure consistency. I advocate for readers, anticipating their questions and providing the information they need. I balance completeness with clarity, knowing that documentation is never finished—it's continuously improved based on feedback and evolving products.

When to Use Me

• Writing API documentation
• Creating user guides and tutorials
• Documenting software architecture
• Writing release notes and changelogs
• Developing help center content
• Creating system documentation
• Writing technical blog posts
• Training material development
• Compliance documentation

Core Concepts

Audience Analysis: Understanding who will read the documentation.

Information Architecture: Organizing content for findability.

Single Sourcing: Creating content that can be reused across formats.

Task-Based Writing: Organizing around user tasks, not features.

Procedural Writing: Clear step-by-step instructions.

Style Guides: Standards for consistency in voice, tone, and formatting.

Versioning: Managing documentation across product versions.

DITA/XML: Structured documentation frameworks.

Code Examples

Example 1: API Documentation Generator

#!/usr/bin/env python3
"""
API Documentation Generator
"""
from dataclasses import dataclass, field
from typing import List, Dict, Optional
from datetime import datetime
from enum import Enum
import json
import re

class HTTPMethod(Enum):
    GET = "GET"
    POST = "POST"
    PUT = "PUT"
    PATCH = "PATCH"
    DELETE = "DELETE"

@dataclass
class Parameter:
    name: str
    type: str
    required: bool
    description: str
    default: Optional[str] = None
    example: Optional[str] = None

@dataclass
class RequestExample:
    language: str
    code: str

@dataclass
class ResponseExample:
    status_code: int
    description: str
    schema: Dict
    example: Dict

@dataclass
class :
    path: 
    method: HTTPMethod
    summary: 
    description: 
    parameters: [Parameter]
    request_body: []
    responses: [ResponseExample]
    authentication_required: 
    tags: []
    examples: [RequestExample]


 :
    title: 
    version: 
    description: 
    base_url: 
    endpoints: [APIEndpoint]
    authentication: 
    rate_limiting: 
    errors: []

 :
     ():
        .endpoints: [APIEndpoint] = []
        .common_parameters: [Parameter] = []
    
     ():
        .endpoints.append(endpoint)
    
     ():
        .common_parameters.append(parameter)
    
     () -> :
        
        spec = {
            : ,
            : {
                : ,
                : ,
                : 
            },
            : [{: }],
            : {},
            : {
                : {
                    : {
                        : ,
                        : ,
                        : 
                    }
                },
                : {
                    : {
                        : ,
                        : {
                            : {: },
                            : {: },
                            : {: , : {: }}
                        }
                    }
                }
            }
        }
        
         endpoint  .endpoints:
            path_item = ._build_path_item(endpoint)
             endpoint.path   spec[]:
                spec[][endpoint.path] = {}
            spec[][endpoint.path][endpoint.method.value.lower()] = path_item
        
         spec
    
     () -> :
         {
            : endpoint.summary,
            : endpoint.description,
            : endpoint.tags,
            : [{: []}]  endpoint.authentication_required  [],
            : [
                {
                    : param.name,
                    : ,
                    : param.required,
                    : {: param.},
                    : param.description,
                    : param.example
                }
                 param  endpoint.parameters
            ],
            : ._build_request_body(endpoint)  endpoint.request_body  ,
            : ._build_responses(endpoint)
        }
    
     () -> :
         {
            : (p.required  p  endpoint.parameters),
            : {
                : {
                    : endpoint.request_body,
                    : endpoint.examples[].code  endpoint.examples  {}
                }
            }
        }
    
     () -> :
        responses = {}
        
         resp  endpoint.responses:
            responses[(resp.status_code)] = {
                : resp.description,
                : {
                    : {
                        : resp.schema,
                        : resp.example
                    }
                }
            }
        
         responses
    
     () -> :
        
        doc = []
        
        doc.append()
        doc.append()
        
        
        by_tag = {}
         endpoint  .endpoints:
             tag  endpoint.tags:
                 tag   by_tag:
                    by_tag[tag] = []
                by_tag[tag].append(endpoint)
        
         tag, endpoints  by_tag.items():
            doc.append()
            
             endpoint  endpoints:
                doc.append()
                doc.append()
                
                 endpoint.parameters:
                    doc.append()
                    doc.append()
                    doc.append()
                     param  endpoint.parameters:
                        req =   param.required  
                        doc.append()
                
                doc.append()
                 resp  endpoint.responses:
                    doc.append()
                
                doc.append()
        
         .join(doc)
    
     () -> :
        
        collection = {
            : {
                : ,
                : 
            },
            : []
        }
        
         endpoint  .endpoints:
            item = {
                : endpoint.summary,
                : {
                    : endpoint.method.value,
                    : [],
                    : {
                        : endpoint.path,
                        : [, , ],
                        : endpoint.path.strip().split()
                    }
                },
                : [
                    {
                        : ,
                        : ,
                        : resp.status_code,
                        : json.dumps(resp.example, indent=)
                    }
                     resp  endpoint.responses
                ]
            }
            
            collection[].append(item)
        
         collection



generator = APIDocumentationGenerator()


generator.add_endpoint(APIEndpoint(
    path=,
    method=HTTPMethod.GET,
    summary=,
    description=,
    parameters=[
        Parameter(
            name=,
            =,
            required=,
            description=,
            default=,
            example=
        ),
        Parameter(
            name=,
            =,
            required=,
            description=,
            default=,
            example=
        )
    ],
    request_body=,
    responses=[
        ResponseExample(
            status_code=,
            description=,
            schema={: , : {: {: }}},
            example={: [{: , : }]}
        ),
        ResponseExample(
            status_code=,
            description=,
            schema={: },
            example={: , : }
        )
    ],
    authentication_required=,
    tags=[],
    examples=[]
))


openapi_spec = generator.generate_openapi_spec()
markdown_docs = generator.generate_markdown_docs()

(json.dumps(openapi_spec, indent=))
( + * + )
(markdown_docs)

Example 2: Release Notes Generator

RELEASE_NOTES_TEMPLATE = """
# Release Notes {version}

**Release Date:** {date}
**Version:** {version}
**Type:** {release_type}  # major, minor, patch

## What's New

### New Features
{fmt_features}

### Improvements
{fmt_improvements}

### Bug Fixes
{ fmt_bugfixes}

### Breaking Changes
{breaking_changes}

## Upgrade Guide

{upgrade_guide}

## Deprecations

{deprecations}

## Known Issues

{known_issues}

## Full Changelog

{full_changelog}

---

*For full documentation, visit [docs.example.com](https://docs.example.com)*
"""

class ReleaseNotesGenerator:
    def __init__(self):
        self.changes = {
            'features': [],
            'improvements': [],
            'bugfixes': [],
            'breaking_changes': [],
            'deprecations': []
        }
        self.known_issues = []
    
    def add_feature(self, title: str, description: str, pr_number: str = None, 
                   contributor: str = None):
        self.changes['features'].append({
            'title': title,
            'description': description,
            'pr': pr_number,
            'contributor': contributor
        })
    
    def add_improvement(self, title: str, description: str, pr_number: str = None):
        self.changes['improvements'].append({
            'title': title,
            : description,
            : pr_number
        })
    
     ():
        .changes[].append({
            : title,
            : description,
            : pr_number
        })
    
     ():
        .changes[].append({
            : description,
            : migration_guide
        })
    
     () -> :
         ():
              items:
                 
             .join(
                
                 item  items
            )
        
         RELEASE_NOTES_TEMPLATE.(
            version=version,
            date=datetime.now().strftime(),
            release_type=release_type,
            fmt_features=fmt_section(.changes[]),
            fmt_improvements=fmt_section(.changes[]),
            fmt_bugfixes=fmt_section(.changes[]),
            breaking_changes=._format_breaking_changes(),
            upgrade_guide=._format_upgrade_guide(),
            deprecations=._format_deprecations(),
            known_issues=._format_known_issues(),
            full_changelog=._generate_changelog_link(version)
        )

Best Practices

• Know your audience and write for them
• Use active voice and clear, concise language
• Follow consistent style guides
• Organize information hierarchically
• Use examples and visuals
• Write task-oriented documentation
• Review and test documentation regularly
• Version control documentation with code
• Automate documentation generation where possible
• Seek feedback from users

Core Competencies

• API documentation
• User guides and tutorials
• Release notes
• System documentation
• Style guide development
• Information architecture
• Content strategy
• Technical blogging
• Video tutorials
• Accessibility in documentation
• Version control for docs
• Single sourcing
• Structured authoring (DITA)
• Localization/translation
• Documentation tooling