|
| 1 | +# 2. Post Type Taxonomy Design |
| 2 | + |
| 3 | +Date: 2026-03-16 |
| 4 | + |
| 5 | +## Status |
| 6 | + |
| 7 | +Accepted |
| 8 | + |
| 9 | +## Context |
| 10 | + |
| 11 | +The blog-workflow plugin needed a systematic way to classify blog posts. Without clear post types, content becomes inconsistent in structure, voice, and reader expectations. Users asked questions like "what kind of post should this be?" without clear guidance. |
| 12 | + |
| 13 | +Key requirements identified: |
| 14 | + |
| 15 | +- Cover common technical blog content patterns |
| 16 | +- Distinguish by purpose, voice, and structure |
| 17 | +- Support progressive complexity (tutorials vs deep dives) |
| 18 | +- Handle temporal relationships (planning → retrospective) |
| 19 | +- Allow living documents vs static snapshots |
| 20 | + |
| 21 | +## Decision |
| 22 | + |
| 23 | +We adopt a **19-type taxonomy** organized across multiple dimensions: |
| 24 | + |
| 25 | +### Post Types |
| 26 | + |
| 27 | +1. **Tutorial** - Authoritative teaching |
| 28 | +2. **Walk-through** - Exploratory process documentation |
| 29 | +3. **Deep Dive** - Industry-oriented technical depth |
| 30 | +4. **Research** - Academic-style investigation |
| 31 | +5. **Study Review** - Learning reflection |
| 32 | +6. **Review** - External evaluation (with subtypes) |
| 33 | +7. **Comparison** - Side-by-side analysis |
| 34 | +8. **Problems** - Issue crystallization |
| 35 | +9. **Open Questions** - Possibility exploration |
| 36 | +10. **Planning** - Pre-work goal setting |
| 37 | +11. **Retrospective** - Post-work reflection |
| 38 | +12. **Updates** - Progress narrative |
| 39 | +13. **Opinions** - Personal perspective |
| 40 | +14. **Dev Blog** - Evergreen practitioner wisdom |
| 41 | +15. **Announcement** - Declaration |
| 42 | +16. **Reference** - Curated collection |
| 43 | +17. **ELI5** - Simplified explanation |
| 44 | +18. **5 Levels** - Progressive complexity explanation |
| 45 | + |
| 46 | +### Dimensions |
| 47 | + |
| 48 | +- **Formality** (1-4): Casual → Structured → Formal → Academic |
| 49 | +- **Complexity** (1-5): Accessible → Introductory → Intermediate → Advanced → Expert |
| 50 | +- **Temporality**: Before, During, After, Atemporal, Point-in-time |
| 51 | +- **Living**: Per-post toggle for maintained documents |
| 52 | + |
| 53 | +### Relationships |
| 54 | + |
| 55 | +Posts connect via explicit frontmatter relationships: |
| 56 | + |
| 57 | +- `series` - Ordered sequence membership |
| 58 | +- `project-arc` - Planning → Updates → Retrospective |
| 59 | +- `responds-to` - Response to another post |
| 60 | +- `supersedes` / `superseded-by` - Replacement relationship |
| 61 | +- `see-also` - Curated related content |
| 62 | + |
| 63 | +### Series as First-Class Entity |
| 64 | + |
| 65 | +Series exist independently in `content/_series/` with their own metadata. Posts declare membership; the build system aggregates. |
| 66 | + |
| 67 | +### Review Subtypes |
| 68 | + |
| 69 | +Reviews use a hybrid approach: |
| 70 | + |
| 71 | +- Built-in subtypes: course, tool, library, book, policy |
| 72 | +- Custom subtypes in `content/_templates/reviews/` |
| 73 | +- Universal fields + subtype-specific fields |
| 74 | + |
| 75 | +## Consequences |
| 76 | + |
| 77 | +### Easier |
| 78 | + |
| 79 | +- **Choosing post type**: Decision tree guides selection |
| 80 | +- **Consistent structure**: Templates per type |
| 81 | +- **Reader expectations**: Clear type signals format |
| 82 | +- **Living documents**: Explicit support for maintained content |
| 83 | +- **Series navigation**: Built-in part ordering |
| 84 | +- **Content relationships**: Explicit linking between posts |
| 85 | + |
| 86 | +### More Difficult |
| 87 | + |
| 88 | +- **Learning curve**: 19 types + dimensions to understand |
| 89 | +- **Template maintenance**: More templates to maintain |
| 90 | +- **Edge cases**: Some content may not fit cleanly |
| 91 | +- **Validation complexity**: More fields to validate |
| 92 | +- **Migration**: Existing posts need type assignment |
| 93 | + |
| 94 | +### Mitigations |
| 95 | + |
| 96 | +- Decision tree and type guide documentation |
| 97 | +- Sensible defaults (formality: 2, complexity: 2) |
| 98 | +- Allow untyped posts during migration |
| 99 | +- Clear "when to use" guidance per type |
0 commit comments