Issue #1: Documentation for Future-Self

pocketDevOps Newsletter

Should internal documentation be a high priority in small teams with limited resources? Yes. Even if you're working solo.

Here's why: in a month, you won't remember what you did today. Those decisions that seem obvious now? They'll look questionable later when you've forgotten the context. You'll waste time second-guessing yourself instead of moving forward.

Welcome to the "pocketDevOps" newsletter.
Not subscribed yet? Want the next issue delivered straight to your inbox? Join the newsletter here.
If this email doesn't display correctly, you can read the web version here.

Why bother?

I see this constantly in embedded projects. You debug a timing issue between your MCU and a sensor. You find the solution. You implement it. Six months later, a customer reports a similar issue with a different sensor. You stare at your own code wondering: "Why did I do it this way?" The answer is gone. The context is lost.

Or worse - you're three months into a project when you realize the sensor you chose won't work with your power budget. But you know you evaluated this before. You're sure you had a reason for this choice. Where did you write it down? Nowhere. Now you're questioning everything.

Writing things down creates clarity. When you document your work, decisions, and knowledge, planning becomes easier. You can see patterns. You can spot problems before they bite you.

Take this blog as an example. I had this idea floating around in my head for years. "DevOps for small embedded teams." Great concept. Zero execution. Why? No clarity on how to make it work. Then I started documenting my thoughts. Writing them down. Sketching out the framework. Suddenly the pieces clicked together. The pocketDevOps cycle emerged. The testing pyramid made sense. Everything started connecting.

That's the power of documentation for your future self.

Where to Start?

I've been digging through documentation approaches that could work for small embedded teams. Not everything fits our world. We don't have dedicated technical writers. We don't have time for 50-page specifications. We need something lightweight. Something that actually helps us ship products.

Here are the concepts that caught my attention.

Architecture Decision Record (ADR)

This one's gold for embedded projects. You're choosing between three different MCUs. Each has tradeoffs. You document your decision: which MCU, why you chose it, what you considered, what you rejected. One page. Done.

Six months later when someone asks "why this chip?" - you have the answer. When you start the next project, you have a reference. When the chip goes end-of-life, you know exactly what requirements to match.

Perfect for pocketDevOps. Lightweight. High value. No overhead.

Request for Comments (RFC)

RFCs help you think before you code. You're about to design your FW update mechanism. Write an RFC first. Describe your approach. List the alternatives. Discuss the tradeoffs.

Even if you're solo, this forces you to think it through. When you work with others, it gets everyone aligned before you write code. No surprises. No "I thought we were doing it differently."

In small teams, keep it short. Two pages max. Focus on the key decisions.

Docs as Code

Here's where it gets interesting for DevOps. Treat your documentation like code. Store it in Git. Version it. Review it. Build it automatically in your CI/CD pipeline.

Your hardware design docs, FW architecture notes, test procedures - all in markdown files next to your code. When you change the FW, you update the docs in the same commit. Your CI pipeline builds the docs and publishes them automatically.

This fits perfectly with the pocketDevOps philosophy. You're already using Git. You're already using CI/CD. Just add documentation to the flow.

Living Documentation

Philip Markgraf has a brilliant approach: generate documentation from your tests. Your FW tests describe how the system behaves. Extract that into readable documentation automatically.

This is huge for embedded systems. Your test suite becomes your specification. When the tests pass, your documentation is accurate. When requirements change, you update the tests, and the documentation updates automatically.

No more outdated docs. No more manual synchronization. The documentation lives with your code.

Listen to this episode from Agile Embedded Podcast. Phil explains it better than I can:

Diátaxis

Diátaxis organizes documentation into four types: tutorials, how-to guides, reference, and explanation. It's more relevant when you're documenting products for external users or building internal knowledge bases.

For pocketDevOps in small teams, this might be overkill. But if you're building a platform that multiple teams use, or if you're documenting your embedded software framework for reuse, Diátaxis gives you a solid structure.

Engineering Handbooks

Handbooks work well if you're growing beyond solo work. When you have three engineers, a handbook captures "how we do things here." Your coding standards. Your review process. Your testing approach. Your release procedure.

Start simple. One markdown file. Expand as needed. Store it in Git with your code.

Style Guides and AI Documentation

Three bonus resources. The Chicago Manual of Style is the gold standard for technical writing (NVIDIA's docs show it in action). And if you're thinking about AI assistants reading your documentation, there are specific best practices for structuring content.

These are lower priority for small embedded teams. But if you want to level up your documentation game, check them out:

Your Next Step

Start small. Pick one approach. I'd suggest Architecture Decision Records. Next time you make a significant technical decision, document it. One page. Five minutes. Done.

Then do it again for the next decision. Build the habit. Your future self will thank you.

That's it for this newsletter. I'd love to hear what you think. Email me or catch me on LinkedIn.
I'm Jakub Zawadzki, and I hope to see you in the next one.

Quick note: English isn't my native language. I use AI assistance to help me write more clearly. But all the ideas, experiences, and opinions you read here are 100% mine. If you find any errors in this text, blame me directly, not AI.