# Analyze Existing Book --- task: id: analyze-existing-book name: Analyze Existing Technical Book description: Deep analysis of existing book state to inform revision planning persona_default: book-analyst inputs: - existing_book_path - revision_motivation (why analyze now?) steps: - Scan all chapters and sections to understand book structure - Extract book metadata (title, version, publisher, audience, publication date) - Analyze structural organization (parts, chapters, sections, learning flow) - Inventory all code examples (count, languages, versions, complexity) - Identify technology versions currently used in book - Extract writing style patterns (voice, tone, heading styles, terminology) - Map cross-references and chapter dependencies - Assess technical currency (what's outdated, deprecated, or broken) - Identify inconsistencies, gaps, or quality issues - Use template book-analysis-report-tmpl.yaml with create-doc.md task - Generate comprehensive analysis report output: docs/analysis/{{book_title}}-analysis-report.md --- ## Purpose This task provides a systematic approach to analyzing an existing technical book before planning revisions. The analysis report becomes the foundation for all brownfield work (2nd editions, version updates, chapter additions, feedback incorporation). ## Prerequisites Before starting this task: - Have access to complete current book content (all chapters) - Know why you're analyzing (new edition? version update? publisher request?) - Understand the target audience and original publication goals - Have access to code repository if one exists ## Workflow Steps ### 1. Scan Book Structure Read through the entire book to understand: - Total chapter count - Part/section organization (if applicable) - Front matter (preface, introduction, how to use this book) - Back matter (appendices, glossary, index) - Overall organization pattern (tutorial-based? reference? project-driven?) Document the table of contents structure completely. ### 2. Extract Book Metadata Collect core information: - Title and subtitle - Author(s) - Current edition/version (1st, 2nd, 3rd) - Publication date (original and current edition if different) - Publisher (PacktPub, O'Reilly, Manning, Self-published) - Target audience (skill level, role, prerequisites) - Current page count - ISBN or product identifiers - Technology stack and versions ### 3. Analyze Structural Organization Evaluate the book's architecture: - How are chapters grouped? (By difficulty? By topic? By project?) - Is there a clear learning progression? - Do chapters build on each other sequentially? - Are there standalone chapters that can be read independently? - Is the structure appropriate for the content? - Does the organization match publisher best practices? ### 4. Inventory Code Examples Catalog all code comprehensively: - Count total code examples - List programming languages used (Python, JavaScript, Go, etc.) - Document technology versions targeted (Python 3.9, Node 16, React 17) - List frameworks and libraries used - Assess code testing status (Is code tested? CI/CD? Manual only?) - Note code repository location (GitHub, GitLab, book companion site) - Categorize example complexity (simple snippets vs. complete projects) - Identify code dependencies between chapters ### 5. Identify Technology Versions For each technology mentioned in the book: - Document current version in book - Find latest stable version available - Identify breaking changes since book publication - Note deprecated features used in book - Flag security vulnerabilities in examples - Assess migration effort (minor updates vs. major rewrites) ### 6. Extract Writing Style Patterns Learn the book's conventions: - Voice and tone (conversational vs. formal, friendly vs. academic) - Structural patterns (typical chapter flow: intro→concept→example→exercise?) - Heading hierarchy style (action-based? question-based? topic-based?) - Terminology choices (consistent? any jargon defined?) - Code comment style (inline comments? docstrings? minimal?) - Callout usage (tips, warnings, notes - frequency and style) - Cross-reference patterns ("see Chapter X", "as discussed in Section Y.Z") This pattern extraction is critical for maintaining consistency in revisions. ### 7. Map Cross-References and Dependencies Document internal dependencies: - Which chapters reference other chapters? - What's the prerequisite flow? (must read Chapter X before Chapter Y) - Which concepts depend on earlier concepts? - Do any code examples build on previous examples? - Are there forward references? ("we'll cover this in Chapter 7") - Are there backward references? ("as we learned in Chapter 4") Create a dependency diagram if helpful. ### 8. Assess Technical Currency Evaluate how current the content is: - Which sections use outdated technology versions? - What APIs or methods are now deprecated? - Are there breaking changes that make examples fail? - Are security best practices current? - Is terminology up-to-date? - Are there discontinued tools or frameworks? - Do examples follow current best practices? Flag specific chapters/sections needing updates. ### 9. Identify Issues and Gaps List problems discovered: - Outdated sections (specific locations) - Broken code examples (won't run on current versions) - Inconsistencies (terminology, formatting, style variations) - Coverage gaps (missing important topics) - Missing deprecated warnings - Technical inaccuracies or errors - Unclear explanations - Unstated assumptions or prerequisites Be specific: note chapter and section numbers. ### 10. Generate Analysis Report Use the create-doc.md task with book-analysis-report-tmpl.yaml template to create the structured analysis document. The report should include all findings from steps 1-9, organized into clear sections. ### 11. Make Recommendations Based on analysis, provide actionable guidance: - Priority updates (critical, important, nice-to-have) - Scope suggestions (full 2nd edition? targeted updates? version migration?) - Timeline estimates (weeks/months for different scope levels) - Risk assessment (what could go wrong?) - Testing strategy recommendations - Learning flow impact considerations - Publisher communication needs ## Success Criteria A completed book analysis should have: - [ ] Complete structural understanding of existing book - [ ] Metadata fully documented - [ ] Code inventory complete with version information - [ ] Technical currency assessment for all technologies - [ ] Writing style patterns extracted - [ ] Cross-reference map created - [ ] All issues and gaps identified with specific locations - [ ] Recommendations provided with priorities - [ ] Analysis report generated and saved - [ ] Report ready to inform revision planning ## Common Pitfalls to Avoid - **Rushing the analysis**: Take time to read thoroughly, don't skim - **Missing code inventory**: Must catalog ALL examples, not just major ones - **Ignoring style patterns**: Pattern extraction is critical for consistency - **Vague issue identification**: Be specific with chapter/section numbers - **No prioritization**: Not all issues are equal - categorize by severity - **Skipping cross-references**: Dependencies affect revision planning ## Next Steps After completing the book analysis: 1. Review analysis report with stakeholders (author, publisher) 2. Use analysis to plan revision (plan-book-revision.md task) 3. Extract code patterns if planning code updates (extract-code-patterns.md) 4. Begin revision planning with clear understanding of current state