Claude-Code-Workflow/.claude/skills/software-manual/specs/quality-standards.md

Quality Standards

Quality gates and standards for software manual generation.

Quality Dimensions

1. Completeness (25%)

All required sections present and adequately covered.

Requirement	Weight	Criteria
Overview section	5	Product intro, features, quick start
UI Guide	5	All major screens documented
API Reference	5	All public APIs documented
Configuration	4	All config options explained
Troubleshooting	3	Common issues addressed
Examples	3	Multi-level examples provided

Scoring:

• 100%: All sections present with adequate depth
• 80%: All sections present, some lacking depth
• 60%: Missing 1-2 sections
• 40%: Missing 3+ sections
• 0%: Critical sections missing (overview, UI guide)

2. Consistency (25%)

Terminology, style, and structure uniform across sections.

Aspect	Check
Terminology	Same term for same concept throughout
Formatting	Consistent heading levels, code block styles
Tone	Consistent formality level
Cross-references	All internal links valid
Screenshot naming	Follow ss-{feature}-{action} pattern

Scoring:

• 100%: Zero inconsistencies
• 80%: 1-3 minor inconsistencies
• 60%: 4-6 inconsistencies
• 40%: 7-10 inconsistencies
• 0%: Pervasive inconsistencies

3. Depth (25%)

Content provides sufficient detail for target audience.

Level	Criteria
Shallow	Basic descriptions only
Standard	Descriptions + usage examples
Deep	Descriptions + examples + edge cases + best practices

Per-Section Depth Check:

• Explains "what" (definition)
• Explains "why" (rationale)
• Explains "how" (procedure)
• Provides examples
• Covers edge cases
• Includes tips/best practices

Scoring:

• 100%: Deep coverage on all critical sections
• 80%: Standard coverage on all sections
• 60%: Shallow coverage on some sections
• 40%: Missing depth in critical areas
• 0%: Superficial throughout

4. Readability (25%)

Clear, user-friendly writing that's easy to follow.

Metric	Target
Sentence length	Average < 20 words
Paragraph length	Average < 5 sentences
Heading hierarchy	Proper H1 > H2 > H3 nesting
Code blocks	Language specified
Lists	Used for 3+ items
Screenshots	Placed near relevant text

Structural Elements:

• Clear section headers
• Numbered steps for procedures
• Bullet lists for options/features
• Tables for comparisons
• Code blocks with syntax highlighting
• Screenshots with captions

Scoring:

• 100%: All readability criteria met
• 80%: Minor structural issues
• 60%: Some sections hard to follow
• 40%: Significant readability problems
• 0%: Unclear, poorly structured

Overall Quality Score

Overall = (Completeness × 0.25) + (Consistency × 0.25) +
          (Depth × 0.25) + (Readability × 0.25)

Quality Gates:

Gate	Threshold	Action
Pass	≥ 80%	Proceed to HTML generation
Review	60-79%	Address warnings, proceed with caution
Fail	< 60%	Must address errors before continuing

Issue Classification

Errors (Must Fix)

• Missing required sections
• Invalid cross-references
• Broken screenshot markers
• Code blocks without language
• Incomplete procedures (missing steps)

Warnings (Should Fix)

• Terminology inconsistencies
• Sections lacking depth
• Missing examples
• Long paragraphs (> 7 sentences)
• Screenshots missing captions

Info (Nice to Have)

• Optimization suggestions
• Additional example opportunities
• Alternative explanations
• Enhancement ideas

Quality Checklist

Pre-Generation

• All agents completed successfully
• No errors in consolidation report
• Overall score ≥ 60%

Post-Generation

• HTML renders correctly
• Search returns relevant results
• All screenshots display
• Theme toggle works
• Print preview looks good

Final Review

• User previewed and approved
• File size reasonable (< 10MB)
• No console errors in browser
• Accessible (keyboard navigation works)

Automated Checks

function runQualityChecks(workDir) {
  const results = {
    completeness: checkCompleteness(workDir),
    consistency: checkConsistency(workDir),
    depth: checkDepth(workDir),
    readability: checkReadability(workDir)
  };

  results.overall = (
    results.completeness * 0.25 +
    results.consistency * 0.25 +
    results.depth * 0.25 +
    results.readability * 0.25
  );

  return results;
}

function checkCompleteness(workDir) {
  const requiredSections = [
    'section-overview.md',
    'section-ui-guide.md',
    'section-api-reference.md',
    'section-configuration.md',
    'section-troubleshooting.md',
    'section-examples.md'
  ];

  const existing = Glob(`${workDir}/sections/section-*.md`);
  const found = requiredSections.filter(s =>
    existing.some(e => e.endsWith(s))
  );

  return (found.length / requiredSections.length) * 100;
}

function checkConsistency(workDir) {
  // Check terminology, cross-references, naming conventions
  const issues = [];

  // ... implementation ...

  return Math.max(0, 100 - issues.length * 10);
}

function checkDepth(workDir) {
  // Check content length, examples, edge cases
  const sections = Glob(`${workDir}/sections/section-*.md`);
  let totalScore = 0;

  for (const section of sections) {
    const content = Read(section);
    let sectionScore = 0;

    if (content.length > 500) sectionScore += 20;
    if (content.includes('```')) sectionScore += 20;
    if (content.includes('Example')) sectionScore += 20;
    if (content.match(/\d+\./g)?.length > 3) sectionScore += 20;
    if (content.includes('Note:') || content.includes('Tip:')) sectionScore += 20;

    totalScore += sectionScore;
  }

  return totalScore / sections.length;
}

function checkReadability(workDir) {
  // Check structure, formatting, organization
  const sections = Glob(`${workDir}/sections/section-*.md`);
  let issues = 0;

  for (const section of sections) {
    const content = Read(section);

    // Check heading hierarchy
    if (!content.startsWith('# ')) issues++;

    // Check code block languages
    const codeBlocks = content.match(/```\w*/g);
    if (codeBlocks?.some(b => b === '```')) issues++;

    // Check paragraph length
    const paragraphs = content.split('\n\n');
    if (paragraphs.some(p => p.split('. ').length > 7)) issues++;
  }

  return Math.max(0, 100 - issues * 10);
}