Issue #1: Documentation for Future-Self

pocketDevOps Newsletter

Welcome to the "pocket DevOps" newsletter.

This is a copy of the newsletter sent to subscribers' inboxes on January 31, 2026.

Not subscribed yet? Want the next issue delivered straight to your inbox? Join the newsletter here: https://pocketdevops.kit.com/sign-up-to-the-newsletter

This is the first newsletter I'm sending out. Let's get started.

Project Update

I've published three blog articles recently. You might be wondering: "why bother with all this theory?"

Here's the thing. These articles lay the foundation for everything coming next. They introduce the "pocket DevOps cycle" concept. They get us on the same page about core ideas and terminology. When I start showing you practical implementations, you'll understand why I made specific choices.

Think of it as setting the stage. Sure, it's not as exciting as hands-on examples. But it matters.

The three articles show where this project is heading:

Now for the practical stuff. It's coming. Setting up the hardware, preparing examples that actually work, testing everything - this takes time. But it's happening. In the meantime, you'll see more articles like the ones above, building the conceptual framework we'll need.

Documentation for Future-Self

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.

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 pocket DevOps 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 pocket DevOps. 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 pocket DevOps 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 pocket DevOps 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 about it. Just hit reply and tell me.

And see you in the next one.

Jakub Zawadzki