documentation
-
🧱 The hardest things
The magic of product development appears to live in the complex things: the clever circuit design, the brilliant algorithm, the integration of many technologies. Observation suggests the opposite. Success is grounded in doing the simple thi…
-
🧹 zephyr-snmp v0.1.0 - a huge cleanup!
zephyr-snmp adds SNMP v1 and v2c support to the Zephyr RTOS. It started as a port of the lwIP SNMP code, and along the way I concluded it would be easier to maintain if it went fully Zephyr-native: Zephyr code style, Zephyr APIs, etc. What …
-
📝 You can't improve an email
I’ve been moving discussions out of email and into versioned Markdown files. Here’s what I’m noticing. Email has a structural problem: the only options are reply and quote. The original message can never be improved. When someone joins a pr…
-
💡 A Simple Example
The Release First mindset starts with how you handle reasonably complex information (a procedure, technical details, etc). There are two approaches: Email or message the information. Put it in Git and send a link or PR. The first is trans…
-
🔵 The Big Blue Button
In the past days, we’ve been focusing on the Big Green Button, but there is another side of this - what happens after the release? Does the release get used? If not, why not? If a release does not get used, there is little point in releasin…
-
📖 When should you write the user manual?
Most of the time, teams write the user manual at the end of a product development cycle right before the Big 1.0 Release. It is one of those things that is not much fun, and teams subconsciously put it off while fighting bigger fires. But w…
-
🔍 It is often more work to review something than to do it
As an experienced person, I am sometimes called on to review something. This can be a frustrating, seemingly hopeless task. With one developer, I commented that he could write code faster than I could review it. While there are some issues …
-
🤝 A release is what unifies Engineering and Business
Some feedback on yesterday’s post (What is a release): What specifically flows into the two points? Value? Effort? Perhaps a better way to phrase this is these are the two points of focus that unify the development team with the rest of t…
-
🔍 AI coding requires better inputs and robust verification
Some great feedback on the previous post (Impressive is not always effective): “I agree. It would be interesting, however, to compare the progression of AI code generation with that of compilers - were there star assembly-code engineers sa…
-
✨ Impressive is not always effective
When AI generates something, the result is often “impressive.” We might marvel at how quickly lots of code is generated that mostly works. Generated documentation is extremely detailed and well formatted. AI-created diagrams are colorful, u…
-
🔄 Platform Thinking is a habit
Platform Thinking in the context of product development has many parallels to effective habits in personal life. With personal exercise, healthy eating, getting enough sleep, and reading good books - these are difficult to start, but easy o…
-
🔄 Breaking the AI slop cycle
“AI Slop” is a common expression describing a familiar phenomenon. It refers to sloppy code (or other assets) generated by AI that mostly works, lacks proper review, and may be poorly architected or implemented. The primary characteristic o…
-
📝 Tips for working with Markdown
Markdown is now a nearly universal format for documentation in many workflows. A few tips for being effective with Markdown: Use a standard editor most of the time (VS Code, Vim, Helix, etc.). This is faster than graphical “Markdown” editor…
-
📝 DDPD - 🧪 TDPD - 🚀 RDPD
We have been discussing document, test, and release-driven development (doing these things first before implementing features). This ensures the product: Meets the customer’s needs (DDPD). Is quality (TDPD). Can be modified any time and re…
-
📝 DDPD - Document Driven Product Development
Building on TDPD and RDPD, Document-driven product development (DDPD) offers another perspective. Ideas: Document the feature from the user’s perspective before implementing anything. Keep the documentation close to the code (same repo, et…
-
✍️ Why writing is important
Some people are wildly successful without writing. So, if the goal is only to make a lot of money or have a lot of power, this advice may not apply. However, for those who want to: Think better Scale ideas beyond direct personal contact Ca…
-
🤝 The benefits of sharing
I wrote my first Claude plugin that packages up some commands that I use in about every project I work on. This plugin allows me to have these commands globally so I don’t have to keep copying them from project to project. Although the comm…
-
💡 Reflections from AI-coding a 10,000 line app
Lessons from AI-coding a 10,000 line app BRun is getting usable. Claude Code wrote almost all of it using Doc-driven development (manually write/update the docs, and have Claude write the code). Some thoughts: Claude is fast – there is no …
-
🔓 You should not be needed
An effective process, team, or organization should be able to continue on if any individual steps away for a bit, or forever. But, most people are insecure and like to be needed, so subconsciously structure things to require them to be pres…
-
📚 Without docs
Design files (mechanical, electrical, or software) contain the technical details that allow us to manufacture something in the moment, but they often don’t contain the “why”. Why is this mechanical feature present? Why is this circuit nece…
-
📚 Documentation never has to go out of date again
AI is really good at updating documentation after implementation. While I strongly advocate writing the documentation to drive AI, inevitably, the implementation takes some unanticipated turns, so making sure everything is in sync after imp…
-
📚 Keep documentation close to the design/code
I find it works best to keep documentation as close to the code or design files as possible. There are several benefits: You can update, commit, and review documentation as part of the standard working process (pull requests, CI, etc.) You…
-
📝 Document "why" not "how"
Be kind to others (and your future self) and document why you did something. AI is pretty good at generating the “how” any time you need it, but only you know the “why” because you have that context.
-
💰 Ways to reduce your AI costs
AI is not free, as there are significant costs associated with training and hosting modern AI models. Some ideas on how to reduce costs with tools like Claude Code: If you do something that is somewhat repetitive, have AI generate scripts …
-
📁 Git* solves the problem of managing files
The thing you get with Git* is a sane way to manage files: organization (team/repo/directories) documentation (excellent support for Markdown) efficient navigation (links in READMEs and other markdown files) history (who changed what when)…
-
🔄 AI and documentation - close the loop
Starting with good documentation is often a better way to use AI. However, you can also close the loop and have AI update the documentation when it is finished. It can fill in details, clean things up, etc. This closes the loop. Then repeat…
-
🤖 AI is the new compiler
There are two ways to use AI: Start with a vague prompt and keep prompting until we get the result we want. Point the AI at documentation, and keep updating the documentation until it is clear enough that AI can do the right thing. Even t…
-
✍️ Effective communication (Written)
For starters, consider Michael Lynch’s “Underused Techniques for Effective Emails”. A few points in summary: Put the most important information first. Use headings, code blocks, and other formatting. Be succinct. Provide context by quoting…
-
🔄 Flipping the playbook for AI coding
A lot of focus these days is on “good AI prompts.” Some of the best prompts may be documentation and tests. Write your CHANGELOG.md entries first, then update the documentation, then write the tests, then tell the AI to update the code to m…
-
📝 Documentation is part of the process, not an afterthought
One of the best productivity hacks ever is to change your thinking about documentation. Most documentation is done after the fact, which is a rather distasteful task at this phase. If we learn to use documentation as part of our thinking/de…
-
📝 Personal vs. collaborative documentation
Yesterday, we discussed the importance of a personal note-taking tool. We can also extend this concept to a team or company using Wikis, Markdown in Git, shared Google Docs, etc. Collaborative documentation is very valuable – IF you can get…
-
🙋 How to help yourself?
Did you ever have the experience going back into a project you have not touched for 6 months – why did I make this change? Or did you ever struggle to get all the dependencies installed to build a project you wrote? Or did you ever wonder –…