Step 4: Document Requirements Analysis
Goal
Define all requirements for the final markdown document: format, style, structure, visual elements, and technical specifications. This becomes the "style guide" for chapter writing.
Inputs Required
| Input | Source | Purpose |
|-------|--------|---------|
| Revised syllabus | syllabus_revised.md | Final structure |
| Topic analyses | topic_analysis/*.md | Content requirements |
| Target audience info | Original articles | Tone reference |
Process
4.1 Audience Definition
Define who will read this guide:
## Target Audience
### Primary Audience
- **Who:** Developers, technical professionals using AI tools
- **Knowledge Level:** Familiar with AI basics, use ChatGPT/Claude occasionally
- **Pain Points:** Inconsistent AI results, frustration with outputs
- **Goals:** Get better results, save time, work more effectively
### Secondary Audience
- **Who:** Managers, team leads, non-technical professionals
- **Knowledge Level:** Basic AI awareness, limited hands-on experience
- **Pain Points:** Don't know where to start, team adoption challenges
- **Goals:** Understand the concept, implement with team
### Audience Balance
- Technical depth: 60% accessible, 40% technical
- Examples split: Include both technical and non-technical
- Jargon: Define terms on first use, avoid unnecessary complexity
4.2 Document Format Specification
## Document Format
### File Format
- **Primary:** Markdown (.md)
- **Export targets:** PDF, potentially HTML/web
### Document Structure
guide.md ├── Title page ├── Table of contents (auto-generated) ├── Introduction ├── Part 1 │ ├── Chapter 1 │ │ ├── Section 1.1 │ │ ├── Section 1.2 │ │ └── Chapter summary │ └── Chapter 2 │ └── ... ├── Part 2 │ └── ... ├── Appendix A: Quick Reference ├── Appendix B: Resources └── About the Author
### Length Guidelines
| Component | Target Length |
|-----------|---------------|
| Introduction | 500-800 words |
| Chapter (average) | 3,000-5,000 words |
| Section (average) | 500-1,000 words |
| Chapter summary | 100-200 words |
| Total guide | 25,000-40,000 words |
4.3 Style Guide
## Writing Style Guide
### Voice & Tone
- **Voice:** First person ("I discovered...", "In my experience...")
- **Tone:** Professional but conversational, like explaining to a smart colleague
- **Formality:** Semi-formal, contractions okay, no slang
### Language Rules
1. **Active voice preferred:** "AI processes the context" not "The context is processed by AI"
2. **Short sentences:** Average 15-20 words per sentence
3. **Short paragraphs:** 3-5 sentences max
4. **Define jargon:** First use of technical term includes brief definition
5. **No fluff:** Every sentence must add value
### Formatting Rules
1. **Headers:** Use ## for chapters, ### for sections, #### for subsections
2. **Lists:** Use bullet points for unordered, numbers for sequential steps
3. **Code blocks:** Use ``` for any code, prompts, or structured text
4. **Emphasis:** Bold for key terms, italic for titles/quotes
5. **Quotes:** Use > blockquote for external citations
### Example: Good vs Bad Writing
**Bad:**
"The utilization of contextual information in the facilitation of AI-based task completion is fundamentally important for achieving optimal outcomes in various scenarios."
**Good:**
"Good context leads to good AI output. Here's why: AI doesn't know your project, your goals, or your constraints. You have to tell it."
4.4 Visual Elements Requirements
## Visual Elements
### Diagrams Needed
| Diagram | Chapter | Description | Format |
|---------|---------|-------------|--------|
| Prompt vs Context | Ch 1 | Box diagram showing components | ASCII or image |
| Task template | Ch 2 | Visual template layout | Code block |
| Workflow diagram | Ch 5 | Tool usage flow | ASCII or image |
| Decision tree | Ch 3 | "When to start fresh" | ASCII or image |
### Tables Needed
| Table | Chapter | Content |
|-------|---------|---------|
| Tool comparison | Ch 5 | Perplexity vs Claude vs ChatGPT |
| Common mistakes | Ch 3 | Mistake + Solution |
| 10 Advices | Appendix | Quick reference |
### Example Boxes
Format for before/after examples:
❌ Bad Example: "Fix the bug"
✅ Good Example: "Fix the bug in UserController.js line 45. Users can't save their profile. Error: 'undefined is not a function'. Expected: Save should update database."
### Code/Prompt Blocks
- Use syntax highlighting where applicable
- Include comments for complex prompts
- Show realistic, not toy examples
4.5 Citation & Attribution Requirements
## Citations & Attribution
### Internal Citations (Your Content)
- Reference original article where appropriate
- Format: "As discussed in [Article Title]..."
- No formal citation needed for your own content
### External Citations
Required format:
"[Quote text]" — Author Name, Source/Platform, Year
### Citation Index
Maintain list at end of guide:
References
- Karpathy, A. (2025). "Context engineering" tweet. Twitter/X.
- Chroma Research. (2025). "Context Rot: How Long Context Affects Performance."
- Lutke, T. (2025). Internal Shopify memo on AI adoption. ...
### Attribution Rules
1. Always attribute direct quotes
2. Paraphrased ideas need attribution if specific to that source
3. General knowledge doesn't need attribution
4. When in doubt, attribute
4.6 Consistency Checklist
## Consistency Requirements
### Terminology
| Term | Use | Don't Use |
|------|-----|-----------|
| Context engineering | ✓ | Context crafting, context design |
| AI tool | ✓ | AI assistant, AI helper |
| Prompt | ✓ (for the input) | Query, request, command |
| Context | ✓ (for background info) | Background, data, information |
### Formatting Consistency
- [ ] All chapters use same header levels
- [ ] All code blocks use same style
- [ ] All examples follow same format (❌/✅)
- [ ] All quotes formatted identically
- [ ] All lists use consistent punctuation
### Naming Consistency
- [ ] "Chapter" not "Section" for top-level
- [ ] "Section" for sub-sections
- [ ] Consistent numbering (1.1, 1.2 vs 1a, 1b)
4.7 Technical Specifications
## Technical Specifications
### Markdown Flavor
- **Use:** GitHub Flavored Markdown (GFM)
- **Tables:** Supported
- **Task lists:** Supported
- **Footnotes:** Use [^1] format if needed
### Special Characters
- Use Unicode where needed (✓, ✗, →, etc.)
- Avoid characters that may break PDF conversion
- Test special characters in target formats
### File Organization
guide_draft/ ├── 00_frontmatter.md ├── 01_introduction.md ├── 02_part1_chapter1.md ├── 03_part1_chapter2.md ├── ... ├── 99_appendix.md └── guide_assembled.md (final combined file)
### Line Length
- Soft wrap at 80-100 characters for readability in editors
- No hard line breaks within paragraphs
Output: document_spec.md
# Context Engineering Guide - Document Specification
## Version: 1.0
## Date: [date]
---
## 1. Audience
[Audience definition from 4.1]
## 2. Format
[Format specification from 4.2]
## 3. Style Guide
[Style rules from 4.3]
## 4. Visual Elements
[Visual requirements from 4.4]
## 5. Citations
[Citation rules from 4.5]
## 6. Consistency
[Consistency checklist from 4.6]
## 7. Technical Specs
[Technical specs from 4.7]
---
## Quick Reference for Writers
### Before Writing Each Chapter:
1. Review this spec
2. Check terminology table
3. Know your visual elements needed
### While Writing:
1. Follow voice/tone guidelines
2. Use correct formatting
3. Add citations as you go
### After Writing:
1. Run consistency check
2. Verify all visuals included
3. Check against spec
Quality Criteria
| Criterion | Check | |-----------|-------| | Audience clearly defined | ☐ | | Format specifications complete | ☐ | | Style guide actionable | ☐ | | Visual elements listed with locations | ☐ | | Citation format defined | ☐ | | Terminology table complete | ☐ | | Technical specs tested | ☐ |
Time Estimate
- Audience definition: 15-20 minutes
- Format specification: 20-30 minutes
- Style guide creation: 30-45 minutes
- Visual elements planning: 20-30 minutes
- Citation rules: 15-20 minutes
- Consistency checklist: 15-20 minutes
- Technical specs: 15-20 minutes
Total: 2-3 hours
Next Step
→ Once document_spec.md is complete, proceed to 05_introduction_writing.md