Adapted from Lesson 8, “Make Your Work Observable,” in The Engineer’s Operating System by Abid Jamil, printed pages 33–34 (PDF pages 34–35). First published as this website article on 7 October 2026. Explore the book.
Good work needs an explanation
A difficult engineering problem can take weeks to solve and only a sentence to describe badly. A status update that says a service was refactored or a migration was completed tells people what happened. It may tell them very little about why the work mattered. The people deciding priorities, supporting customers or maintaining the system later need the connection between technical effort and its consequences.
Making work observable means helping those people understand the problem, the decisions and the result. It does not require a constant stream of announcements. A short explanation backed by evidence can be more useful than a long inventory of tasks. The aim is to make an important outcome understandable enough for someone else to act on it.
Move from activity to impact
Start with the condition that needed to change. Was a workflow difficult to maintain? Were users waiting too long? Did a recurring failure create operational work? Then explain the engineering action in the context of that problem. This gives technical detail a purpose instead of asking the reader to infer one.
Finish with the result you can support. Where measurements exist, include a meaningful before-and-after comparison and enough context to interpret it. Where a benefit is qualitative, describe the observable change honestly. A simpler integration process or a documented decision can matter even when you cannot attach a reliable percentage to it. Separate what was measured from what you expect to improve.
Leave evidence other people can use
Architecture decisions, internal demonstrations, postmortems and performance measurements are useful records of engineering judgment. They explain not only the final implementation but also what the team learned. A future maintainer can revisit the constraints. Another team can reuse an approach. A manager can understand the value of work that is otherwise easy to overlook.
Keep the record proportionate to the decision. A small change may need a clear pull request description; a significant architectural change may deserve a decision note and a demonstration. When sharing outside the organization, remove confidential details and discuss the general lesson. Visibility should increase the usefulness of the work without compromising the people or systems behind it.
Try a three-line project review
Choose one recent project. Write one line describing the problem, one explaining the engineering action, and one stating the measured or observable impact. Ask a colleague outside the immediate project to read it. If they cannot explain why the work mattered, revise the description before adding more technical detail.
Key takeaways: lead with the problem, connect decisions to consequences, preserve useful evidence, and be precise about what you know. Good communication helps good engineering travel beyond the person who did it. It allows an outcome to be remembered, reused and recognized for the value it created.