Posts

Documentation Is Part of the Platform Contract and Makes Your Agents Better

-
Platform teams often treat documentation as the final step before launch. That is backwards. If developers cannot understand, evaluate, and safely use a capability, the capability is not finished. Good documentation is more than a collection of setup instructions. It is part of the interface between a platform team and its users. Like any interface, it needs clear ownership, predictable structure, and ongoing maintenance. That has always mattered for developers. In an AI-enabled engineering organization, it matters even more. Documentation exposes platform complexity When a basic task requires a long guide filled with exceptions, the documentation is not necessarily the problem. It may be revealing unnecessary complexity in the product. That makes documentation work valuable design feedback. Ask an engineer unfamiliar with the service to follow the guide. Watch where assumptions appear, terminology shifts, or required decisions lack context. Those points often indicate that the platfor...
Post a Comment
Read more

Standardize Delivery Outcomes, Not Every Team’s Workflow

-
Engineering leaders often pursue standardization by asking every team to use the same workflow. The intent is reasonable: reduce risk, simplify support, and make delivery easier to govern. But identical workflows are rarely the right goal. A mobile application, a shared library, and a regulated backend service have different release constraints. Forcing them through one rigid process creates workarounds, manual exceptions, and resentment toward the platform. The better approach is to standardize the outcomes that matter while allowing teams flexibility in how they achieve them. Define the delivery contract A delivery contract describes what must be true before software reaches production. It should focus on observable controls rather than a prescribed sequence of tools and pipeline stages. For example, the contract might require: Traceable source, build, artifact, and deployment records Automated security and policy checks A tested rollback or recovery mechanism Clear service...
Post a Comment
Read more

Make Toil Reduction Part of Capacity Planning

-
Most engineering organizations say they want to reduce toil. Far fewer reserve capacity to do it. That gap matters. Repetitive operational work rarely disappears through good intentions. It competes with product delivery, security requirements, incidents, and customer commitments. Unless leaders account for toil during planning, teams will keep absorbing it as an unofficial tax. Toil is a capacity problem Manual access changes, recurring deployment fixes, repetitive incident recovery, and routine environment maintenance consume real engineering time. They also interrupt concentration and make delivery less predictable. Leaders often treat this work as the cost of operating a system. Some of it is. The mistake is accepting the same cost indefinitely without deciding whether automation, simplification, or removal would be a better investment. Do not ask teams to eliminate toil alongside a fully committed roadmap. Make the tradeoff visible. If reducing a recurring task requires ...
Post a Comment
Read more

The Best Deployment Approval Is the One You Can Remove

-
Manual deployment approvals often begin as a reasonable response to risk. Over time, they become permanent fixtures, even when they add little protection. A person clicks a button, but rarely has enough context to independently validate the change. The approval delays delivery while creating the appearance of control. Leaders should ask a harder question: what evidence would allow us to remove this step? Replace permission with evidence Approval gates are most useful when judgment is genuinely required. They are less useful when reviewers simply confirm that automated checks passed or that a ticket contains the expected fields. Those conditions should be enforced by the delivery system. Build pipelines can verify test results, security policies, artifact provenance, change windows, and deployment readiness more consistently than a hurried reviewer. The objective is not to eliminate accountability. It is to make accountability explicit and repeatable. Define an approval remo...
Post a Comment
Read more

Build Platform Roadmaps Around Friction, Not Features

-
Internal platform teams often inherit the planning habits of customer-facing product teams. They create feature backlogs, publish quarterly roadmaps, and celebrate shipped capabilities. That approach can produce a busy team without producing a better engineering system. A platform is valuable when it removes friction from software delivery. The roadmap should reflect that purpose. Start With the Cost of Friction Platform planning should begin with how engineers currently get work done. Where do they wait? Which tasks require tickets? Where do teams create their own scripts because the supported path is incomplete? These questions reveal more than a list of feature requests. They expose recurring costs across the organization: delayed environments, inconsistent deployment patterns, duplicated pipelines, unclear ownership, and security controls applied too late. A request from one team may be an isolated preference. The same workaround appearing across several teams is evidence of a...
Post a Comment
Read more

An Error Budget Without a Decision Rule Is Just a Dashboard

-
Error budgets are useful because they translate reliability into a constraint the business can understand. But many organizations stop after calculating the number and displaying it on a dashboard. That is not an operating model. If consuming the entire error budget changes nothing, the budget has no authority. It is another metric teams can acknowledge and ignore. Define the consequence before the incident Leaders should agree on decision rules while services are healthy. Waiting until reliability deteriorates invites negotiation under pressure. Product leaders will defend commitments, engineering teams will debate severity, and customers will continue absorbing the impact. A practical policy should answer a few direct questions: What happens when budget consumption exceeds an agreed threshold? Which releases may continue, and which must pause? Who can approve an exception? What evidence is required before normal delivery resumes? The response should be proportional. ...
Post a Comment
Read more

Stop Measuring Your Platform by Adoption Alone

-
Platform adoption is easy to celebrate. More teams using the deployment pipeline, service catalog, or infrastructure templates appears to prove that the platform is working. But adoption alone can hide an uncomfortable reality. Teams may use the platform because it is mandatory, while still losing time to confusing workflows, missing capabilities, and slow support. A platform can have near-universal usage and still deliver a poor developer experience. Measure the Friction Removed The purpose of an internal platform is not to centralize tools. It is to reduce the effort required to build, deliver, and operate software safely. Technology leaders should therefore look beyond registration counts and pipeline executions. Better questions focus on the work developers can complete without waiting for another team. Can a team create a production-ready service without filing tickets? Can developers understand why a deployment failed? Can teams make routine infrastructure changes th...
Post a Comment
Read more