Learning to drive digital platforms
This article is a follow-on to the previous post, “An analogy for digital platforms”. In this article we further explore delivery-van metaphor and make some recommendations that platform teams can implement to help consumers use their platform safely, confidently, and effectively.
When consumers can ‘drive’ a platform effectively, the entire business benefits from faster time-to-market, higher reliability, a stronger security posture, and improved developer productivity. It’s not just about making developers happy; it’s about creating a competitive advantage through the optimisation of software delivery.
Learning to drive the van
We take it for granted that you need a licence to drive a van. It’s a legal requirement, but it’s also just common sense. Without training, practice, and a shared understanding of the standard controls, you might be able to lurch down the road—but you wouldn’t be safe, efficient, or confident.
Drivers don’t start by studying the van’s complex underlying systems (the engine, gearbox, hydraulics etc). Instead they learn:
- The simple, standardised controls (steering, accelerator, brake, gears, signals)
- The rules of the road (the Highway Code)
- How to integrate with other road users
- How to handle different conditions
- Practical skills through hours of guided practice
Only then do they take a test to demonstrate they can operate the van competently in the real world.
Platforms often skip the driving lessons
Many platforms don’t provide an equivalent “learning to drive” step. We’re often vague about what the platform does, when and crucially how it should be used. This leaves platform consumers uninformed and guessing, which leads to confusion within the organisation and frustration on both sides.
Some common unanswered questions include:
- What workloads does the platform support?
- How do potential platform consumers know whether a given workload is suitable (and supported) by the platform?
- Which phases of the software lifecycle are covered by the platform (build, test, deploy, operate, decommission)?
- What other capabilities does the platform provide? (e.g. observability, alerting, software composition analysis, change management integration etc)
- What capabilities does the platform provide that make it stand out against other platforms?
- What non-functional capabilities does the platform provide? (MTTR targets, RTO/RPO, availability guarantees, geographical redundancy, backup/restore etc)
- How opinionated is the platform? Are there areas where platform consumers can choose from options (e.g. database engines, message brokers), and what are the trade‑offs?
- What are the guardrails vs. the “off‑piste” areas? What support (or lack of it) comes with going off the beaten path?
- How do platform consumer teams onboard and offboard—people, services, credentials, billing, and data?
- How should platform consumers interact with the platform: CLI, API, GitOps, UI—or a combination?
If platform consumers don’t understand what the platform offers, when and how to use it, then it becomes much harder for them to make decisions which will benefit them and the organisation. It’s like asking someone to drive a van without explaining how to drive it.
So how do you teach someone to drive a platform?
The following sections provide some suggestions on how to provide platform consumers with sufficient information to confidently use a platform to deliver their software:
Create a single place to learn
Every driver needs instruction and a set of lessons. Platform consumer teams need the same, these can be implemented in a number of ways:
- A platform handbook or portal that explains capabilities, interfaces, limits, rules and expectations
- Up‑to‑date, versioned documentation tied to real platform releases
- Task‑oriented guides that mirror the consumer team journey (onboard a service, set up CI/CD, deploy, scale, observe and alert, configure secrets, roll back safely etc)
- Reference architectures and paved‑road examples that show the “right way” to use the platform
The format matters less than the usefulness: whether it’s a handbook, developer portal, or embedded docs in a console. Make it discoverable, accurate, and tested like code.
Show, don’t just tell: examples and tutorials
Driving is learned primarily by doing. Providing the following can help platform consumers learn by interacting with the platform itself:
- Working example repos for supported workload types (e.g. Web frontend, scheduled worker, event consumer)
- End‑to‑end demo pipelines showing consumers how to build, test, deploy, and operate on the platform
- Short tutorial videos or guided walkthroughs
- Copy‑paste snippets for CLI/API/GitOps interactions
Keep these examples alive. Test them in CI so they don’t rot. Ensure they are kept up-to-date with the platform as its capabilities change.
Evangelise and enable
In the physical world, instructors help new drivers become safe and confident. In platform land, platform-enablement or platform-dev‑rel teams can play that role:
- Proactively visit platform consumer teams; avoid waiting for tickets
- Offer clinics and office hours
- Pair with platform consumer teams on their first service onboarding
- Capture FAQs and fold them back into platform documentation and examples
Have regular service MOTs
Vans typically provide driver feedback via dashboards and warning lights. Some of these, such as collision detection systems, are designed to pre-emptively keep the van safe. Others, such as oil level lights, alert the driver to sub-optimal conditions that needs to be addressed quickly to keep the van in good working order.
Platforms should offer similar feedback mechanisms to their consumers, to help keep their services within platform guardrails. Some common examples of this include:
- Automated feedback in pipelines to provide consumers with actionable and early feedback e.g.
- Code linting - Identify areas where code does not meet coding standards
- Static code analysis - Identify areas of consumer code which do not meet safety standards
- Test pass rate - Identify failing tests and provide correlation data to identify which commit broke each test
- Assert platform guardrails are being followed, correctly e.g. Correct use of HTTP client timeouts / TLS / identity / auditing etc
- Vulnerability scan results etc - Identify any dependencies containing known vulnerabilities
- Automated platform readiness checks (sometimes known as “platform passports”) that show where platform consumer services are / are not adhering to platform guardrails.
- Clear feedback on the platform’s resulting support posture where consumer services are “off-piste” and do not adhere to platform guardrails.
It is important that platform guardrail non-compliances are described clearly, and that actionable remediation guidance is provided, informing consumers how to regain compliance with platform guardrails.
Crucially, consumers should not have to expend significant effort to obtain this information, the platform should provide it pro-actively and automatically, making it readily available for consumers to utilise and act on.
Listen to the road noise
Despite best efforts to keep things on track, things will go wrong. Sometimes there’s a nail in the road which can’t be avoided, and there’s nothing like the sound of driving on a flat tyre to make you realise something is wrong.
Platforms typically have a wealth of data they can use to identify these sorts of situations: Looking at support requests from platform consumers, user research, and platform telemetry can all help identify friction, gaps, and misunderstandings and then improve the associated platform experiences.
Looking at these areas should be a BAU exercise for platform teams, and should contribute to the continuous improvement and development of the platform as a product.
Conclusion: Learning doesn’t stop when you get your licence
Drivers don’t stop learning to improve our driving just because they have passed their test. In fact, passing their test shows that they have demonstrated the minimum amount of skill required to drive the van safely. They then continue to develop their driving skills with every journey offering feedback and learning opportunities.
A good platform will provide its consumers with similar offerings
- Teach teams how to use the standardised controls, so that they can deliver their services safely and efficiently
- Provide a safe, paved road that’s clearly signposted, providing consistency for each software deliver journey
- Offer guidance and feedback when and where it matters most: early and actionably
- Continuously improve the platform driving experience based on real usage
By doing this, platform consumers are transformed from novices to experts, who can deliver software confidently, reliably and safely, without needing to open the bonnet. This is how an organisation unlocks its platform’s true business potential and translates platform engineering into a competitive advantage.
We’d Love Your Feedback
Have you implemented any of the suggestions made in the article? Did they work for you? Do you have any other suggestions which you have found effective? I’d love to hear from you! Feel free to drop me a message and share your thoughts.
Notes
- The image used in this article was generated by Google Gemini.