atxtechbro / atxtechbro/dotfiles

feat(retro): incorporate Brooksian documentation principles into post-PR retros

Open
#664 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
Shell
Stars
27
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## Problem

Our post-PR retros focus well on systems improvement but could benefit from Fred Brooks' wisdom about documentation tradeoffs. We're missing opportunities to capture architectural insights and balance precision with communicativeness.

## Proposed Enhancement

Enhance the post-PR mini retro procedure with Brooks-inspired questions that examine our documentation and communication practices.

## Suggested Retro Additions

### Documentation Tradeoffs Section
Add these prompts to the retro procedure:

**Brooks' Precision vs. Communicativeness Check:**
- Where were we overly precise but hard to understand?
- Where did we favor clarity but risk important ambiguity?
- Did our documentation capture the "why" or just the "what"?

**Architectural Discovery:**
- What assumptions were invalidated during implementation?
- What would we tell someone implementing this feature next time?
- Should this learning be captured in architecture decisions?

**Documentation Debt:**
- What knowledge is still tribal/in our heads?
- What diagrams would have helped?
- Where did we discover the docs were wrong?

## Implementation Ideas

1. **Create docs/architecture-decisions/ directory**
- Capture "why" not just "what"
- Use ADR (Architecture Decision Record) format
- Include discovery stories

2. **Add "Lessons Learned" to PR template**
- What we thought vs. what we learned
- Architectural insights discovered
- Documentation that needs updating

3. **Monthly "Mythical Man-Month" principle**
- Rotate Brooks quotes/principles in retros
- Apply them to current work
- Build a culture of reflective documentation

## Example Brooks Principles for Retros

- "The bearing of a child takes nine months, no matter how many women are assigned"
- "Plan to throw one away; you will, anyhow"
- "Adding manpower to a late software project makes it later"
- "The documentary hypothesis: Writing decisions down is essential"

## Why This Matters

Per the Snowball Method, 20% of our time should improve systems. Documentation *is* a system - one that compounds knowledge over time. Brooks teaches us that good documentation isn't about being exhaustive; it's about finding the sweet spot between precision and understanding.

## Success Criteria

- Retros capture more "aha\!" moments
- Fewer repeated mistakes across PRs
- Documentation that future us (and future AI agents) can actually use
- Balance between "accurate" and "understandable"

Principle: systems-stewardship
Principle: transparency-in-agent-work

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by locating the post-PR mini retro procedure and PR template referenced by the issue, then review whether a docs/architecture-decisions/ directory already exists. Define the implementation scope before changing anything; done should include an agreed way to capture documentation tradeoffs, architectural discoveries, and lessons learned in retros.

Written by the indexing model from the issue text.

Assessment

Domain
developer-experience, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.