8.4 KiB

Raw Blame History

Technical Review Chapter

task: id: technical-review-chapter name: Technical Review Chapter description: Comprehensive technical accuracy review with fact-checking, code validation, security audit, and best practices assessment persona_default: technical-reviewer inputs: - chapter-draft - chapter-number - subject-area-expertise steps: - Read chapter draft completely for overview - Verify technical accuracy against official documentation - Review all code examples for correctness and best practices - Test code examples to ensure they run properly - Check for security vulnerabilities in code - Assess performance implications of recommendations - Identify outdated information or deprecated features - Note factual errors or misconceptions - Compile findings into structured review report - Assign severity levels to issues (Critical/Major/Minor) - Provide constructive recommendations with sources - Run execute-checklist.md with technical-accuracy-checklist.md - Run execute-checklist.md with security-best-practices-checklist.md - Run execute-checklist.md with performance-considerations-checklist.md - Use template technical-review-report-tmpl.yaml with create-doc.md output: reviews/technical-review-chapter-{{chapter_number}}.md

Purpose

This task performs a rigorous technical review to ensure all content is accurate, current, secure, and follows best practices. Technical reviewers act as subject matter experts validating the chapter's technical correctness before publication.

Prerequisites

Chapter draft completed
Access to official documentation for technologies covered
Subject matter expertise in chapter topics
Code testing environment available
Access to technical-writing-standards.md knowledge base

Workflow Steps

1. Read Chapter Draft Completely

Get the full context before detailed review:

Read entire chapter without stopping to take notes
Understand the learning objectives
Note the target audience level
Identify all technologies and concepts covered
Get a sense of overall quality

Purpose: Understand context before nitpicking details.

2. Verify Technical Accuracy

Check all technical claims against authoritative sources:

For Each Technical Claim:

Is this factually correct?
Is it current (not outdated)?
Can it be verified in official documentation?
Are version numbers specified correctly?

Sources to Check:

Official language documentation (Python.org, MDN, etc.)
Framework official docs
RFCs and standards specifications
API documentation
Release notes

Document Issues:

Location (section, page, paragraph)
Incorrect statement
Correct information
Source reference
Severity (Critical if wrong, Minor if imprecise)

Use: technical-accuracy-checklist.md

3. Review Code Examples for Correctness

Validate all code in the chapter:

For Each Code Example:

Syntax and Logic:

Does the code have syntax errors?
Will it run as shown?
Does it produce the claimed results?
Are there logic errors?

Completeness:

Are all imports shown?
Are dependencies clear?
Is setup code included or explained?
Can a reader actually run this?

Accuracy:

Does the code use APIs correctly?
Are parameters in the right order?
Are return types correct?
Is error handling appropriate?

Action: Copy code to test environment and run it!

4. Check Best Practices

Assess whether code follows current best practices:

Code Quality:

Follows language style guides (PEP 8, ESLint, etc.)
Uses meaningful variable names
Includes appropriate comments
Avoids deprecated features
Handles errors properly

Design Patterns:

Uses appropriate patterns
Avoids anti-patterns
Demonstrates scalable approaches
Shows proper separation of concerns

Modern Approaches:

Uses current language features
Leverages modern libraries
Follows framework conventions
Demonstrates industry standards

Note: Balance teaching clarity with production quality - sometimes simple is better for learning.

5. Identify Security Concerns

Review for security vulnerabilities:

Critical Issues:

Hardcoded credentials or API keys
SQL injection vulnerabilities
XSS (Cross-Site Scripting) risks
Insecure authentication
Missing input validation
Unsafe deserialization

Best Practices:

HTTPS/TLS usage
Password hashing (bcrypt, Argon2)
JWT secret management
API rate limiting
Logging security events
Principle of least privilege

For Each Security Issue:

Describe the vulnerability
Explain potential impact
Provide secure code example
Reference security standard (OWASP, CWE)
Mark severity (Critical for exploitable issues)

Use: security-best-practices-checklist.md

6. Assess Performance Implications

Consider performance and scalability:

Inefficiencies:

O(n²) algorithms where O(n) is possible
N+1 query problems
Missing database indexes
Unnecessary iterations or computations
Memory leaks or excessive allocation

Scalability:

Will this approach scale to production?
Are there resource constraints?
Is caching appropriate?
Are there blocking operations in async code?

Recommendations:

Better algorithms or data structures
Optimization techniques
Profiling suggestions
When optimization matters vs premature optimization

Use: performance-considerations-checklist.md

7. Note Outdated Information

Check currency of all technical content:

Deprecated Features:

Language features no longer recommended
Framework APIs deprecated
Tools superseded by newer alternatives

Version Issues:

Library versions outdated or EOL
Examples using old syntax
Missing modern alternatives

Update Recommendations:

Current best practices
Modern equivalents
Migration paths
Version updates needed

Example: "Using React class components; recommend hooks-based functional components (current standard since React 16.8)"

8. Compile Findings into Review Report

Create structured technical review report:

Use template: technical-review-report-tmpl.yaml

Report Sections:

Executive summary (overall assessment)
Technical accuracy findings
Code quality issues
Security concerns
Performance considerations
Best practices assessment
Outdated information
Positive findings (what worked well)
Prioritized recommendations

Assign Severity:

Critical: Must fix (factual errors, security issues, broken code)
Major: Should fix (best practice violations, performance issues)
Minor: Nice to fix (style improvements, optimization suggestions)

9. Provide Constructive Recommendations

For each issue, provide actionable guidance:

Good Feedback Format:

Location: Section 2.3, page 12, code example
Issue: Using `collections.MutableMapping` which is deprecated
Severity: Major
Recommendation: Use `collections.abc.MutableMapping` instead (Python 3.3+)
Source: https://docs.python.org/3/library/collections.abc.html
Fixed Code:
from collections.abc import MutableMapping
class MyDict(MutableMapping):
    ...

Be Constructive:

Explain why it's wrong
Show how to fix it
Provide source reference
Offer example code where helpful

Avoid:

Vague criticism ("this is bad")
Nitpicking without explaining why
Rewriting the entire chapter
Focusing only on negatives

10. Run Technical Checklists

Validate against standard checklists:

Execute:

technical-accuracy-checklist.md
security-best-practices-checklist.md
performance-considerations-checklist.md

Document any checklist items that fail.

Output

Technical review report should include:

Clear severity ratings for all issues
Specific locations for every finding
Actionable recommendations with examples
Source references for claims
Overall assessment (Ready/Needs Revision/Major Rework)
Estimated effort to address issues

Quality Standards

Effective technical review:

✓ Verifies every technical claim ✓ Tests all code examples ✓ Identifies security vulnerabilities ✓ Provides constructive feedback ✓ Includes source references ✓ Prioritizes issues by severity ✓ Offers concrete solutions ✓ Maintains respectful, professional tone

Next Steps

After technical review:

Deliver review report to author
Author addresses issues based on priority
Re-review critical fixes (optional)
Approve chapter to proceed to copy editing
May participate in final publication review

8.4 KiB Raw Blame History