After 18 years in tech, I’ve seen documentation fail in almost every way possible. From outdated wikis that no one reads to massive Google Doc graveyards that make your eyes glaze over. But I’ve also discovered what actually works. Here’s the real deal on documentation that people will actually use.

The Hard Truth About Documentation

Let’s be honest: most engineering documentation is terrible. Not because engineers can’t write (though some of us certainly prefer code), but because we’re thinking about documentation all wrong. We treat it like a checkbox to tick off rather than a tool to help our teams move faster.

Video Documentation: The Game Changer

Here’s my “personal fav” approach that has consistently worked: Record short, focused videos. Why?

1. It’s faster to create. You can record a 5-minute technical deep-dive in… well, 5 minutes. Writing that same content might take an hour.
2. People actually consume it. Engineers are more likely to watch a quick video showing how to set up a local environment than read a 20-page setup guide.
3. It captures context you can’t write. When you’re explaining why you made certain architectural decisions, tone and emphasis matter.

The Documentation Stack That Actually Works

Here’s my hierarchy of documentation, from most to least important:

1. README.md Files

• Lives with the code
• Explains how to get started
• Lists core dependencies
• Shows basic usage examples
• Must be maintained or CI fails

2. Quick Video Walkthroughs

• 5-10 minutes max
• One specific topic per video
• Screen recording + voice explanation
• Perfect for:
  • Debugging common issues
  • Setting up development environments
  • Walking through new features
  • Explaining architectural decisions

3. Living Architecture Documents

• High-level system design
• Core architectural decisions
• Update when major changes happen
• Keep it brief – link to videos for details

4. Runbooks

• Step-by-step emergency procedures
• Must be tested regularly
• Include common failure scenarios
• Link to monitoring dashboards

Make Documentation Actually Maintainable

Here’s what I’ve learned about keeping docs alive:

1. Treat documentation like code:

• Version control it
• Review it during PRs
• Test it (yes, really)
• Delete it when it’s obsolete – make sure you have a forcing function to revisit old docs

2. Write less, but better:

• One source of truth
• Link don’t copy
• Update or delete
• No “TODO” sections (we all know they never get done)

The Documentation Workflow That Works

Here’s my actual process for creating documentation that sticks:

1. Start with a video:

• Record yourself explaining the concept – I use OBS since it’s free and lets me record myself, my screen, and pairs nicely with a StreamDeck that I use to do everything in a single cut.
• Share with the team
• Get feedback
• Iterate if needed (I use FinalCut Pro to edit my videos, but I try to make net-new videos if possible)

2. Extract key points:

• Turn video insights into bullet points, link to timestamps in your video.
• Add to README or architecture doc
• Link to the video for details

3. Create runbooks from real incidents:

• Document while solving problems
• Update with each new incident
• Include links to relevant videos

Common Documentation Pitfalls to Avoid

Don’t make these mistakes I’ve seen kill documentation efforts:

1. The “Someone Else Will Do It” Trap

• If you’re working on it, you document it
• No exceptions

2. The “I’ll Document It Later” Lie

• Document while you work
• Use screen recording to capture your process
• It’s never “later”
• Add a calendar invite for an hour in your own calendar to make sure it gets done, set it to recurring on a daily basis as your reminder.

3. The “Everyone Knows This” Fallacy

• New team members exist
• Future you will forget as your brain attic gets cluttered with more stuff
• Document the obvious, it’s not obvious to everyone – teaching others will help you retain and learn too

Make Your Documentation Count

Here’s what I tell every team I work with:

1. If you’re explaining something more than once, record it
2. If you’re recording it, keep it under 10 minutes. Don’t record meetings, be purposeful about what you record, meetings and questions can drone on, but your succinct video is to the point – you can always have follow-up meetings to chat live about something.
3. If you’re writing it, make it searchable – search and AI-generated content from what you make now is going to be commonplace in the next 5 years.
4. If it’s not maintained, delete it

The Bottom Line

Documentation isn’t about writing novels. It’s about helping your team move faster and making your systems more maintainable. Start with videos, keep your docs close to your code, and ruthlessly delete anything that’s not providing value.