Technical Writing

Name: Technical Writing
Author: proffesor-for-testing

proffesor-for-testing/agentic-qe

155 installs
433 repo stars
Updated August 4, 2026
proffesor-for-testing/agentic-qe

Author clear runbooks, test plans, and n8n workflow docs so agentic-qe teammates and agents can operate, extend, and troubleshoot automations confidently.

About

technical-writing from proffesor-for-testing/agentic-qe helps produce precise documentation—runbooks, test plans, ADRs, and workflow guides—so humans and agents can understand, operate, and extend agentic quality systems.

Runbooks for n8n and test systems
Test-plan and ADR templates
Agent-readable documentation patterns
Reduces onboarding and ops friction
Supports review and strategy skills

Technical Writing by the numbers

155 all-time installs (skills.sh)
+5 installs in the week ending Aug 4, 2026 (Skillselion tracking)
Ranked #563 of 1,879 Documentation skills by installs in the Skillselion catalog
Data as of Aug 5, 2026 (Skillselion catalog sync)

npx skills add https://github.com/proffesor-for-testing/agentic-qe --skill technical-writing

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/proffesor-for-testing/agentic-qe/technical-writing.svg)](https://skillselion.com/skills/proffesor-for-testing/agentic-qe/technical-writing)

Installs	155
repo stars	★ 433
Last updated	August 4, 2026
Repository	proffesor-for-testing/agentic-qe ↗

What it does

Author clear runbooks, test plans, and n8n workflow docs so agentic-qe teammates and agents can operate, extend, and troubleshoot automations confidently.

Files

SKILL.mdMarkdownGitHub ↗

Technical Writing

<default_to_action> When writing technical content: 1. LEAD with value (what will reader learn/gain?) 2. SHOW, don't tell (specific examples, code, numbers) 3. STRUCTURE for scanning (headers, bold, short paragraphs) 4. CUT ruthlessly (every sentence must earn its place) 5. BE honest about trade-offs

Blog Post Structure:

# Title (specific promise)

## Opening (2-3 paragraphs)
- Hook: The problem or insight
- Context: Why this matters
- Promise: What they'll learn

## Body (3-5 sections)
- One clear idea per section
- Support with examples/code/data

## Closing
- Key takeaway (1-2 sentences)
- Action reader can take

Before/After: ❌ "We implemented a comprehensive testing strategy..." ✅ "We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement." </default_to_action>

Quick Reference Card

Core Principles

Principle	Bad	Good
Lead with value	"In today's landscape..."	"Here's how we cut bugs 60%"
Show, don't tell	"We improved testing"	"Bug detection: 12→47 per sprint"
Be specific	"Performance improved"	"Response time: 2.3s→180ms"
Honest trade-offs	"This approach is best"	"TDD slowed velocity 20%, reduced bugs 75%"

Words to Cut

Kill	Reason
basically, actually, probably	Hedge words
leverage, synergy, paradigm	Corporate speak
very, really, quite	Unnecessary qualifiers
it should be noted that	Just note it

---

Audience-Specific Writing

For Developers

Lead with code or concrete problem
Show implementation details
Discuss trade-offs and alternatives
Link to repos or examples

For QA/QE

Start with testing challenge
Show strategy, not just tools
Include risk assessment
Provide adaptable heuristics

For Leadership

Open with business impact
Use metrics that matter
Connect technical to outcomes
Keep technical details concise

---

Editing Checklist

Before publishing:

[ ] Title promises something specific
[ ] Opening hooks in 30 seconds
[ ] Claims backed by examples
[ ] All unnecessary words cut
[ ] Code examples tested and correct
[ ] Takeaway crystal clear
[ ] Would send to respected colleague

---

Example Transformations

Before: "We decided to implement a more comprehensive testing strategy that would allow us to catch bugs earlier in the development lifecycle."

After: "We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement, identifying risks before code is written."

---

Before: "The benefits of this approach are numerous and include improved quality, faster feedback loops, and better team collaboration."

After: "Three outcomes: bugs found 2 days earlier on average, 30% fewer regression issues, and devs now ask QE for input during design."

---

Agent Integration

// Generate documentation from code
const docs = await Task("Generate Docs", {
  source: 'src/services/PaymentService.ts',
  format: 'markdown',
  includeExamples: true
}, "qe-quality-analyzer");

// Review documentation quality
const review = await Task("Review Docs", {
  files: ['README.md', 'docs/api.md'],
  checkClarity: true,
  checkCodeExamples: true
}, "qe-quality-analyzer");

---

Agent Coordination Hints

Memory Namespace

aqe/technical-writing/
├── generated-docs/*   - Auto-generated documentation
├── reviews/*          - Documentation review findings
└── templates/*        - Reusable doc templates

Fleet Coordination

const docsFleet = await FleetManager.coordinate({
  strategy: 'documentation',
  agents: [
    'qe-quality-analyzer',         // Generate and review
    'qe-api-contract-validator'    // API doc accuracy
  ],
  topology: 'sequential'
});

---

Related Skills

bug-reporting-excellence - Technical bug writing
code-review-quality - Review documentation

---

Remember

You're not writing to impress. You're writing to help people solve problems you've already solved. Be the colleague you wish you'd had.

Write from experience. Only write about what you've done in production. If exploring, say so.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agentic-qe.dev/schemas/skills/technical-writing/output.json",
  "title": "Technical Writing Skill Output Schema",
  "description": "Schema for technical-writing skill output. Clear, engaging technical documentation with structure and clarity assessment.",
  "type": "object",
  "required": ["skillName", "version", "timestamp", "status", "trustTier", "output"],
  "properties": {
    "skillName": {
      "type": "string",
      "const": "technical-writing"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "status": {
      "type": "string",
      "enum": ["success", "partial", "failed", "skipped"]
    },
    "trustTier": {
      "type": "integer",
      "const": 3
    },
    "output": {
      "type": "object",
      "required": ["summary", "documentStructure", "clarity", "completeness"],
      "properties": {
        "summary": {
          "type": "string",
          "minLength": 20,
          "maxLength": 2000
        },
        "documentStructure": {
          "$ref": "#/$defs/documentStructure"
        },
        "clarity": {
          "$ref": "#/$defs/clarity"
        },
        "completeness": {
          "$ref": "#/$defs/completeness"
        },
        "content": {
          "type": "string",
          "maxLength": 100000,
          "description": "The generated documentation content"
        },
        "sections": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/section"
          }
        },
        "styleAnalysis": {
          "$ref": "#/$defs/styleAnalysis"
        },
        "recommendations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/recommendation"
          },
          "maxItems": 50
        },
        "readabilityMetrics": {
          "$ref": "#/$defs/readabilityMetrics"
        },
        "qualityScore": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        "grade": {
          "type": "string",
          "pattern": "^[A-F][+-]?$"
        },
        "metrics": {
          "$ref": "#/$defs/metrics"
        }
      }
    },
    "metadata": {
      "$ref": "#/$defs/metadata"
    },
    "validation": {
      "$ref": "#/$defs/validationResult"
    },
    "learning": {
      "$ref": "#/$defs/learningData"
    }
  },
  "$defs": {
    "documentStructure": {
      "type": "object",
      "required": ["type", "hasIntroduction", "hasConclusion"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["tutorial", "reference", "guide", "api-docs", "readme", "adr", "specification", "report", "proposal"]
        },
        "hasIntroduction": { "type": "boolean" },
        "hasConclusion": { "type": "boolean" },
        "hasTableOfContents": { "type": "boolean" },
        "sectionCount": { "type": "integer", "minimum": 0 },
        "headingDepth": { "type": "integer", "minimum": 1, "maximum": 6 },
        "hasCodeExamples": { "type": "boolean" },
        "hasDiagrams": { "type": "boolean" },
        "structureScore": { "type": "number", "minimum": 0, "maximum": 100 },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": { "type": "string" },
              "message": { "type": "string" },
              "severity": { "type": "string", "enum": ["error", "warning", "suggestion"] }
            }
          }
        }
      }
    },
    "clarity": {
      "type": "object",
      "required": ["score"],
      "properties": {
        "score": { "type": "number", "minimum": 0, "maximum": 100 },
        "grade": { "type": "string", "pattern": "^[A-F][+-]?$" },
        "dimensions": {
          "type": "object",
          "properties": {
            "sentenceClarity": { "type": "number", "minimum": 0, "maximum": 100 },
            "terminologyConsistency": { "type": "number", "minimum": 0, "maximum": 100 },
            "ambiguityFree": { "type": "number", "minimum": 0, "maximum": 100 },
            "logicalFlow": { "type": "number", "minimum": 0, "maximum": 100 }
          }
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "text": { "type": "string" },
              "issue": { "type": "string" },
              "suggestion": { "type": "string" },
              "location": { "type": "string" }
            }
          }
        }
      }
    },
    "completeness": {
      "type": "object",
      "required": ["score"],
      "properties": {
        "score": { "type": "number", "minimum": 0, "maximum": 100 },
        "requiredSections": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "present": { "type": "boolean" },
              "quality": { "type": "number", "minimum": 0, "maximum": 100 }
            }
          }
        },
        "missingTopics": { "type": "array", "items": { "type": "string" } },
        "incompleteSections": { "type": "array", "items": { "type": "string" } }
      }
    },
    "section": {
      "type": "object",
      "required": ["title", "content"],
      "properties": {
        "id": { "type": "string" },
        "title": { "type": "string" },
        "content": { "type": "string" },
        "level": { "type": "integer", "minimum": 1, "maximum": 6 },
        "wordCount": { "type": "integer", "minimum": 0 },
        "subsections": {
          "type": "array",
          "items": { "$ref": "#/$defs/section" }
        }
      }
    },
    "styleAnalysis": {
      "type": "object",
      "properties": {
        "voice": { "type": "string", "enum": ["active", "passive", "mixed"] },
        "tone": { "type": "string", "enum": ["formal", "informal", "technical", "conversational"] },
        "audienceLevel": { "type": "string", "enum": ["beginner", "intermediate", "advanced", "expert"] },
        "consistency": { "type": "number", "minimum": 0, "maximum": 100 },
        "styleGuideCompliance": {
          "type": "object",
          "properties": {
            "guide": { "type": "string" },
            "compliance": { "type": "number", "minimum": 0, "maximum": 100 },
            "violations": { "type": "array", "items": { "type": "string" } }
          }
        }
      }
    },
    "readabilityMetrics": {
      "type": "object",
      "properties": {
        "fleschKincaid": { "type": "number" },
        "fleschReadingEase": { "type": "number" },
        "gunningFog": { "type": "number" },
        "smog": { "type": "number" },
        "avgSentenceLength": { "type": "number" },
        "avgWordLength": { "type": "number" },
        "wordCount": { "type": "integer" },
        "sentenceCount": { "type": "integer" },
        "paragraphCount": { "type": "integer" }
      }
    },
    "recommendation": {
      "type": "object",
      "required": ["id", "title", "priority"],
      "properties": {
        "id": { "type": "string", "pattern": "^REC-\\d{3,6}$" },
        "title": { "type": "string", "maxLength": 200 },
        "description": { "type": "string", "maxLength": 2000 },
        "priority": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
        "category": { "type": "string", "enum": ["structure", "clarity", "completeness", "style", "formatting"] },
        "example": { "type": "string" }
      }
    },
    "metrics": {
      "type": "object",
      "properties": {
        "wordCount": { "type": "integer", "minimum": 0 },
        "sectionCount": { "type": "integer", "minimum": 0 },
        "codeExampleCount": { "type": "integer", "minimum": 0 },
        "linkCount": { "type": "integer", "minimum": 0 },
        "imageCount": { "type": "integer", "minimum": 0 }
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "executionTimeMs": { "type": "integer", "minimum": 0 },
        "toolsUsed": { "type": "array", "items": { "type": "string" } },
        "agentId": { "type": "string", "pattern": "^qe-[a-z][a-z0-9-]*$" },
        "documentType": { "type": "string" },
        "targetAudience": { "type": "string" }
      }
    },
    "validationResult": {
      "type": "object",
      "properties": {
        "schemaValid": { "type": "boolean" },
        "contentValid": { "type": "boolean" },
        "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
      }
    },
    "learningData": {
      "type": "object",
      "properties": {
        "patternsDetected": { "type": "array", "items": { "type": "string" } },
        "reward": { "type": "number", "minimum": 0, "maximum": 1 }
      }
    }
  }
}