Documentation System

This file explains how our three documentation files work together and stay in sync.

The Three Documents

1. content-strategy.md (Strategy & Tactics)

Purpose: Strategic guidance and tactical patterns

Contains:

• Publishing cadence principles (10-14 days)
• Writing style guidelines (essay structure, observational tone)
• Publication types (regular articles vs synthesis)
• Channel strategy (what/why/how for each platform)
• Cross-post platform timing (Medium +2d, Dev.to ~2wk)
• LinkedIn posting pattern (publish → insight @10d → reflection @25d)
• Reddit engagement tactics (search terms, cadence, reply strategy)
• HN engagement tactics (timing, approach)
• Article roadmap (Phase A/B/C tables with titles + messages)
• External publication requirements

Does NOT contain:

• Specific dated tasks
• Checkboxes/status tracking
• Individual post content

2. distribution-schedule.md (Execution Calendar)

Purpose: Dated tasks with status tracking

Contains:

• Monthly calendar tables with dates
• Checkboxes (✓ done, X cancelled, ✓ outdated)
• Specific tasks (publish, LinkedIn post, Reddit search, etc.)
• Current progress summary at top
• “Last updated” date

Does NOT contain:

• Strategy explanations
• Tactical patterns/guidance
• Article roadmap (references content-strategy.md instead)

3. schedule.ics (Calendar Sync)

Purpose: Machine-readable events for calendar apps

Contains:

• VEVENT entries generated from distribution-schedule.md
• Dates, summaries, descriptions, URLs

Does NOT contain:

• Strategy, tactics, or guidance
• Human-readable explanations

---

Single Sources of Truth

What	Owner	Consumers
Article roadmap (titles, messages)	content-strategy.md	distribution-schedule.md (references only)
Strategy & tactics	content-strategy.md	-
Dated tasks & status	distribution-schedule.md	schedule.ics (generated from)

---

Update Workflows

When You Publish an Article

1. Open distribution-schedule.md
2. Find the publish task for that article
3. Add ✓ checkbox: | Mon 16 | ✓ | 📝 | Publish article 005 |
4. Update “Last updated” date at top
5. Commit: git commit -m "Mark article XXX published"

Do NOT:

• Update content-strategy.md (it doesn’t track status)
• Regenerate schedule.ics manually (if needed, handled separately)

When You Plan New Content

1. Open content-strategy.md
2. Add/modify article in Phase A/B/C roadmap table
3. Open distribution-schedule.md
4. Add dated tasks for publish, LinkedIn, Medium, etc.
5. Update “Last updated” date
6. Commit: git commit -m "Add article XXX to roadmap and schedule"

Do NOT:

• Duplicate article titles/messages between files
• Add strategy/tactics to distribution-schedule.md

When Tactics/Strategy Change

1. Open content-strategy.md
2. Modify the relevant section (e.g., Reddit search terms, LinkedIn pattern)
3. Commit: git commit -m "Update [platform] strategy"

Do NOT:

• Update distribution-schedule.md (it references strategy, doesn’t duplicate it)

When External Plans Change (e.g., InfoQ Rejection)

1. Open distribution-schedule.md
2. Find the milestone task
3. Mark as cancelled: | Tue 7 | ~~X~~ | 📦 | ~~Pitch to InfoQ~~ | Rejected Feb 27 |
4. Update “Current Progress” section at top if needed
5. Update “Last updated” date
6. Open content-strategy.md
7. Update “External Publication Requirements” or “Publication Types” if strategy changed
8. Commit: git commit -m "InfoQ rejected - update distribution plans"

---

Staying In Sync

The Header Comment (distribution-schedule.md)

The header at the top of distribution-schedule.md enforces the separation:

📌 **Article roadmap:** See [content-strategy.md](content-strategy.md)
📌 **Tactics/strategy:** See [content-strategy.md](content-strategy.md)
📌 **This file:** Dated execution calendar only

If you’re about to add strategy/tactics to distribution-schedule.md, this reminder should stop you.

The “Last Updated” Date

Every time you modify distribution-schedule.md, update the date at the top:

*Last updated: 2026-02-28*

This helps identify when the calendar is stale.

Regular Reviews

Monthly: Check that both files align

• Are new articles in both roadmap and calendar?
• Are completed articles marked ✓ in calendar?
• Is “Last updated” recent?

After External Events: Update both if needed

• Publication rejection/acceptance → update calendar + strategy
• New platform strategy → update strategy only
• Article published → update calendar only

---

Common Mistakes to Avoid

❌ Don’t: Add article titles to distribution-schedule.md status table
✅ Do: Reference content-strategy.md for roadmap

❌ Don’t: Add Reddit search terms to distribution-schedule.md
✅ Do: Keep them in content-strategy.md, reference when needed

❌ Don’t: Explain LinkedIn posting pattern in distribution-schedule.md
✅ Do: Keep pattern in content-strategy.md, just date tasks in calendar

❌ Don’t: Track article status in content-strategy.md
✅ Do: Track only in distribution-schedule.md

❌ Don’t: Manually edit schedule.ics
✅ Do: Regenerate from distribution-schedule.md when needed

---

Quick Reference

“Where does this belong?”

Content Type	Destination
Article title/message	content-strategy.md roadmap
Dated publish task	distribution-schedule.md
LinkedIn posting pattern	content-strategy.md
Specific LinkedIn post date	distribution-schedule.md
Reddit search terms	content-strategy.md
Specific Reddit task date	distribution-schedule.md
Why we use Medium	content-strategy.md
When to cross-post to Medium	content-strategy.md (timing), distribution-schedule.md (specific date)
External publication strategy	content-strategy.md
Specific pitch milestone	distribution-schedule.md
Checkboxes/status	distribution-schedule.md only

---

This system was established 2026-02-28 to prevent documentation drift.