atxtechbro / atxtechbro/dotfiles

meta: Stop creating boilerplate .md files - write authentic notes instead

Open
#601 0 comments 0 reactions 0 assignees View on GitHub
cleanup documentation tech-debt
Dominant language
Shell
Stars
27
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## Meta Pattern to Fix
Stop writing corporate documentation. Write authentic notes to future self.

## Bad Pattern Examples
- Creating separate .md files to "document" what's already clear in code
- Writing professional-sounding boilerplate that adds no value
- Explaining WHAT instead of WHY
- Cookie-cutter documentation that could apply to any project

## Good Pattern - Personal Notes Style
```json
"allow": [
"LS", // kept getting prompted when listing dirs
"mcp__filesystem__list_files", // same, annoying popup
// add more as they bug me
]
```

## Philosophy Shift
- **FROM**: "Here's what this does" (obvious from code)
- **TO**: "Yeah I added this because X kept bugging me"
- **FROM**: Professional documentation
- **TO**: Personal reminders and breadcrumbs

## Model for Future Work
- Comments should sound like texts to yourself
- Only document the non-obvious WHY
- If the code is self-explanatory, shut up
- Every .md file needs to justify its existence

## Litmus Test
"Would I thank myself for this note in 6 months, or would I be annoyed at the bloat?"

This is THE issue to reference when I slip back into corporate doc mode.

Principle: subtraction-creates-value

Contributor guide

No contributing guide indexed for this repository

Research direction

No specific file, test, or entry point is named. Review the repository’s existing .md files and the notes in this issue first, then determine which documentation should be removed or rewritten and how the stated litmus test will be applied consistently.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
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.