214 lines
4.8 KiB
Markdown
214 lines
4.8 KiB
Markdown
<!-- Powered by BMAD™ Core -->
|
|
|
|
# Create Appendix
|
|
|
|
---
|
|
|
|
task:
|
|
id: create-appendix
|
|
name: Create Appendix
|
|
description: Develop comprehensive appendix content including reference materials, installation guides, and troubleshooting
|
|
persona_default: technical-editor
|
|
inputs:
|
|
|
|
- appendix-type
|
|
- content-requirements
|
|
- book-chapters
|
|
steps:
|
|
- Identify appendix content (reference tables, installation guides, troubleshooting)
|
|
- Organize by topic
|
|
- Create clear appendix titles
|
|
- Reference from main chapters
|
|
- Include platform-specific installation guides
|
|
- Add troubleshooting FAQ
|
|
- List additional resources (links, books, websites)
|
|
- Ensure consistent formatting
|
|
- Add to table of contents
|
|
- Index appendix content
|
|
- Use template appendix-tmpl.yaml with create-doc.md
|
|
output: back-matter/appendix-{{letter}}.md
|
|
|
|
---
|
|
|
|
## Purpose
|
|
|
|
Create valuable reference appendices that complement the main text and help readers solve common problems.
|
|
|
|
## Workflow Steps
|
|
|
|
### 1. Identify Appendix Content
|
|
|
|
**Common Appendix Types:**
|
|
|
|
- **Appendix A**: Exercise solutions
|
|
- **Appendix B**: Reference tables (HTTP codes, SQL commands, etc.)
|
|
- **Appendix C**: Installation and setup guides
|
|
- **Appendix D**: Troubleshooting and FAQs
|
|
- **Appendix E**: Additional resources
|
|
- **Appendix F**: Glossary of terms
|
|
|
|
### 2. Organize by Topic
|
|
|
|
Structure clearly:
|
|
|
|
```markdown
|
|
# Appendix A: Exercise Solutions
|
|
|
|
## Chapter 1 Solutions
|
|
### Exercise 1.1
|
|
[Solution]
|
|
|
|
### Exercise 1.2
|
|
[Solution]
|
|
|
|
## Chapter 2 Solutions
|
|
[...]
|
|
```
|
|
|
|
### 3. Reference from Chapters
|
|
|
|
Cross-reference effectively:
|
|
|
|
```markdown
|
|
For complete HTTP status code reference, see Appendix B.
|
|
|
|
Try the exercises at the end of this chapter (solutions in Appendix A).
|
|
|
|
Installation instructions for all platforms are in Appendix C.
|
|
```
|
|
|
|
### 4. Platform-Specific Installation
|
|
|
|
Cover all platforms:
|
|
|
|
```markdown
|
|
# Appendix C: Installation Guide
|
|
|
|
## Installing Python
|
|
|
|
### Windows
|
|
1. Download Python 3.11+ from python.org
|
|
2. Run installer, check "Add Python to PATH"
|
|
3. Verify: Open PowerShell and run `python --version`
|
|
|
|
### macOS
|
|
1. Install Homebrew: `/bin/bash -c "$(curl -fsSL...)"`
|
|
2. Install Python: `brew install python@3.11`
|
|
3. Verify: `python3 --version`
|
|
|
|
### Linux (Ubuntu/Debian)
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install python3.11
|
|
python3.11 --version
|
|
```
|
|
```
|
|
|
|
### 5. Troubleshooting FAQ
|
|
|
|
Common issues:
|
|
|
|
```markdown
|
|
# Appendix D: Troubleshooting
|
|
|
|
## Python Issues
|
|
|
|
### Q: "python: command not found"
|
|
**Problem**: Python not in PATH
|
|
**Solution (Windows)**: Reinstall Python, check "Add to PATH" option
|
|
**Solution (Mac/Linux)**: Use `python3` instead of `python`
|
|
|
|
### Q: "ModuleNotFoundError: No module named 'requests'"
|
|
**Problem**: Package not installed
|
|
**Solution**: `pip install requests`
|
|
|
|
## API Issues
|
|
|
|
### Q: 401 Unauthorized errors
|
|
**Causes**:
|
|
- Expired JWT token
|
|
- Missing Authorization header
|
|
- Invalid API key
|
|
|
|
**Solutions**:
|
|
- Refresh token
|
|
- Add header: `Authorization: Bearer [token]`
|
|
- Verify API key in environment variables
|
|
```
|
|
|
|
### 6. Additional Resources
|
|
|
|
Curated links:
|
|
|
|
```markdown
|
|
# Appendix E: Additional Resources
|
|
|
|
## Official Documentation
|
|
- Python Requests Library: https://requests.readthedocs.io
|
|
- Flask Documentation: https://flask.palletsprojects.com
|
|
- FastAPI: https://fastapi.tiangolo.com
|
|
|
|
## Books
|
|
- "RESTful Web APIs" by Leonard Richardson & Mike Amundsen
|
|
- "Designing Data-Intensive Applications" by Martin Kleppmann
|
|
|
|
## Online Resources
|
|
- REST API Tutorial: https://restfulapi.net
|
|
- HTTP Cats (status codes): https://http.cat
|
|
- JSON Placeholder (test API): https://jsonplaceholder.typicode.com
|
|
|
|
## Tools
|
|
- Postman (API testing)
|
|
- Insomnia (API client)
|
|
- HTTPie (command-line HTTP client)
|
|
```
|
|
|
|
### 7. Reference Tables
|
|
|
|
Quick lookup:
|
|
|
|
```markdown
|
|
# Appendix B: HTTP Status Code Reference
|
|
|
|
| Code | Name | Meaning |
|
|
|------|------|---------|
|
|
| 200 | OK | Request succeeded |
|
|
| 201 | Created | Resource created successfully |
|
|
| 204 | No Content | Success but no content to return |
|
|
| 400 | Bad Request | Invalid request syntax |
|
|
| 401 | Unauthorized | Authentication required |
|
|
| 403 | Forbidden | Authenticated but not authorized |
|
|
| 404 | Not Found | Resource doesn't exist |
|
|
| 500 | Internal Server Error | Server-side error |
|
|
| 503 | Service Unavailable | Server temporarily unavailable |
|
|
```
|
|
|
|
### 8. Index Appendix Content
|
|
|
|
Ensure discoverability:
|
|
|
|
```markdown
|
|
\index{HTTP status codes}
|
|
\index{Installation!Python}
|
|
\index{Troubleshooting}
|
|
```
|
|
|
|
## Success Criteria
|
|
|
|
- [ ] Appendix content identified
|
|
- [ ] Organized logically by topic
|
|
- [ ] Clear titles for each appendix
|
|
- [ ] Referenced from main chapters
|
|
- [ ] Platform-specific guides included
|
|
- [ ] Troubleshooting FAQ comprehensive
|
|
- [ ] Additional resources curated
|
|
- [ ] Consistent formatting
|
|
- [ ] Added to table of contents
|
|
- [ ] Content indexed
|
|
|
|
## Next Steps
|
|
|
|
1. Add appendices to back matter
|
|
2. Cross-reference from chapters
|
|
3. Update during technical review
|