You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 67c6386
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: src/content/articles/golden-paths-developer-experience-standardization-autonomy/index.mdx
+14-10Lines changed: 14 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,10 +30,13 @@ There's a better way. Golden paths offer curated, supported ways to accomplish c
30
30
31
31
## What Makes a Path Golden
32
32
33
-
A golden path is a supported, well-documented way to accomplish a common task that the platform team actively maintains and improves. That definition has important implications:
33
+
<Highlighter>A golden path is a supported, well-documented way to accomplish a common task that the platform team actively maintains and improves.</Highlighter> That definition has important implications:
34
34
35
35
<List
36
-
variant="check-icons-list"
36
+
variant="side-by-side-list"
37
+
classes={{
38
+
wrapper: "sm:ml-6 sm:mr-12 mb-6",
39
+
}}
37
40
items={[
38
41
{
39
42
lead: "Opinionated but not mandatory",
@@ -61,7 +64,8 @@ A golden path is a supported, well-documented way to accomplish a common task th
61
64
The difference between a golden path and golden handcuffs comes down to choice:
62
65
63
66
<Table
64
-
variant="vertical-column-delineation-table"
67
+
variant="grid-and-accent-header-table"
68
+
fullWidth={false}
65
69
content={{
66
70
figure: "Golden paths vs. golden handcuffs.",
67
71
thead: {
@@ -99,7 +103,7 @@ But having the right philosophy isn't enough. The mechanism that makes golden pa
99
103
Escape hatches are how teams leave the golden path when they have a legitimate reason. Done well, they're a first-class feature of the platform. Done poorly, they're either so hidden that teams work around them anyway, or so easy that everyone uses them and the path becomes meaningless.
100
104
101
105
<List
102
-
variant="check-icons-list"
106
+
variant="zebra-list"
103
107
items={[
104
108
{
105
109
lead: "Escape hatches should be documented, not hidden",
@@ -120,12 +124,12 @@ Escape hatches are how teams leave the golden path when they have a legitimate r
120
124
]}
121
125
/>
122
126
127
+
The escape hatch mechanism is what distinguishes a golden path from a mandate. Without it, you're not offering a better way — you're demanding compliance. And compliance without capability creates the shadow systems you were trying to prevent.
128
+
123
129
<Callouttype="info">
124
130
Escape hatches without tracking become invisible technical debt. If you don't know who's using alternatives and why, you can't plan path improvements, estimate migration costs, or sunset deprecated options. Every escape hatch usage should be registered.
125
131
</Callout>
126
132
127
-
The escape hatch mechanism is what distinguishes a golden path from a mandate. Without it, you're not offering a better way — you're demanding compliance. And compliance without capability creates the shadow systems you were trying to prevent.
128
-
129
133
## Getting Started: A Prioritized Approach
130
134
131
135
If you're building your first golden path — or trying to fix one that isn't working — here's where to focus. These five priorities are ordered: start at the top and don't skip ahead.
@@ -158,6 +162,10 @@ You're not deploying infrastructure; you're launching a product to internal cust
158
162
159
163
Platform teams with a product mindset build paths that developers love. Platform teams with an infrastructure mindset build paths that developers tolerate — until something better comes along.
160
164
165
+
## Making Standardization the Path of Least Resistance
166
+
167
+
The platform team's job is to make standardization the path of least resistance. When you succeed, shadow infrastructure disappears because there's no reason to build it. Teams adopt standards voluntarily because the alternative is more work. Maintenance burden shifts from every team to the platform team, who can invest deeply in getting it right.
@@ -178,10 +186,6 @@ Platform teams with a product mindset build paths that developers love. Platform
178
186
]}
179
187
/>
180
188
181
-
## Making Standardization the Path of Least Resistance
182
-
183
-
The platform team's job is to make standardization the path of least resistance. When you succeed, shadow infrastructure disappears because there's no reason to build it. Teams adopt standards voluntarily because the alternative is more work. Maintenance burden shifts from every team to the platform team, who can invest deeply in getting it right.
184
-
185
189
This approach requires more upfront investment than mandates. You have to build something worth using, not just declare what's required. You have to listen to feedback and iterate, not just enforce compliance. You have to prove value with data, not just assert it with authority.
186
190
187
191
But the payoff is a platform that developers trust and willingly adopt. A successful golden path doesn't need enforcement. When developers choose your path because it's faster, easier, and better supported, you've built something valuable. That willing adoption is sustainable in a way that mandates never are.
Copy file name to clipboardExpand all lines: src/content/articles/golden-paths-developer-experience-standardization-autonomy/pdf.mdx
+71-38Lines changed: 71 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,20 +23,23 @@ Platform teams want standardization for maintainability, security, and operation
23
23
24
24
Here's the scenario I've seen play out too many times: a platform team mandates a specific deployment pipeline. Teams with legitimate edge cases — ML workloads that need GPU nodes, regulated data that requires specific isolation, real-time systems that can't tolerate the standard rollout strategy — face a choice. They can fight for exceptions (slow, political), work around the mandate (shadow infrastructure), or shoe-horn their use case into an ill-fitting solution (technical debt, operational risk).
25
25
26
-
Morale drops. Shadow platforms emerge. The "standard" becomes optional in practice because enough teams have found workarounds that enforcement is impossible. The mandate failed because it was a golden handcuff, not a golden path.
27
-
28
26
<Callouttype="warning">
29
27
Mandates breed workarounds. When developers can't use the standard path for legitimate reasons and have no sanctioned escape hatch, they'll build shadow infrastructure. You end up with __less__ standardization than if you'd designed for autonomy from the start.
30
28
</Callout>
31
29
30
+
Morale drops. Shadow platforms emerge. The "standard" becomes optional in practice because enough teams have found workarounds that enforcement is impossible. The mandate failed because it was a golden handcuff, not a golden path.
31
+
32
32
## The Philosophy of Golden Paths
33
33
34
34
### What Makes a Path "Golden"
35
35
36
36
A golden path is a supported, well-documented way to accomplish a common task that the platform team actively maintains and improves. That definition has several important implications.
37
37
38
38
<List
39
-
variant="check-icons-list"
39
+
variant="side-by-side-list"
40
+
classes={{
41
+
wrapper: "sm:ml-6 sm:mr-12 mb-6",
42
+
}}
40
43
items={[
41
44
{
42
45
lead: "Opinionated but not mandatory",
@@ -66,7 +69,10 @@ A golden path is a supported, well-documented way to accomplish a common task th
66
69
Three failure modes kill golden paths:
67
70
68
71
<List
69
-
variant="check-icons-list"
72
+
variant="numbered-with-background-list"
73
+
classes={{
74
+
wrapper: "sm:ml-6 sm:mr-12 mb-6",
75
+
}}
70
76
items={[
71
77
{
72
78
lead: "Golden handcuffs",
@@ -88,7 +94,7 @@ Three failure modes kill golden paths:
88
94
Standardization approaches exist on a spectrum from mandates to full self-service, with golden paths in the middle. The table below compares these approaches across four dimensions: how much consistency you achieve, how fast teams can move, how much the platform team invests, and what use cases each approach fits best.
89
95
90
96
<Table
91
-
variant="vertical-column-delineation-table"
97
+
variant="criteria-highlight-table"
92
98
content={{
93
99
figure: "Comparing standardization approaches.",
94
100
thead: {
@@ -114,19 +120,19 @@ Standardization approaches exist on a spectrum from mandates to full self-servic
114
120
/>
115
121
116
122
<List
117
-
variant="check-icons-list"
123
+
variant="zebra-list"
118
124
items={[
119
125
{
120
-
lead: "Mandated standards work for security-critical controls, legal and compliance requirements, and cross-cutting concerns like observability where inconsistency creates real operational risk",
121
-
text: "The tradeoff is high adoption friction and stifled innovation. Use mandates sparingly.",
text: "They work for security-critical requirements, legal compliance, and cross-cutting concerns like observability where inconsistency creates real operational risk. The tradeoff is high adoption friction and stifled innovation. Use mandates sparingly.",
122
128
},
123
129
{
124
-
lead: "Golden paths work for common patterns like service creation and deployment, best practices like testing and monitoring, and productivity tooling",
125
-
text: "The tradeoff is that escape hatches can become the primary path if you're not careful, and paths can become outdated if you under-invest in maintenance.",
text: "They work for service creation and deployment, best practices like testing and monitoring, and productivity tooling. The tradeoff is that escape hatches can become the primary path if you're not careful, and paths can become outdated if you under-invest in maintenance.",
126
132
},
127
133
{
128
-
lead: "Full self-service works for early-stage companies where standardization would slow down finding product-market fit, R&D and experimental work where the whole point is trying new things, and highly heterogeneous tech landscapes where no single path could cover the diversity",
129
-
text: "The tradeoff is duplication of effort, knowledge silos, and operational burden distributed across every team.",
134
+
lead: "Full self-service suits exploration and diversity.",
135
+
text: "It works for early-stage companies where standardization would slow down finding product-market fit, R&D work where the whole point is trying new things, and heterogeneous tech landscapes where no single path could cover the diversity. The tradeoff is duplication of effort, knowledge silos, and operational burden distributed across every team.",
130
136
},
131
137
]}
132
138
/>
@@ -144,10 +150,11 @@ A well-designed golden path has five components: an entrypoint, a core journey,
144
150
The best golden path is useless if developers don't know it exists or can't figure out which one applies to their situation. Path discovery is the zero-th step that makes everything else possible.
145
151
146
152
<List
147
-
variant="check-icons-list"
153
+
variant="numbered-with-background-list"
148
154
items={[
149
155
{
150
-
text: "A service catalog (Backstage, Port, or similar) gives developers a searchable, browsable home for all paths. Each path has a card with a description, use cases, getting-started link, and owner contact. Developers searching for \"create a new service\" or \"set up monitoring\" find the relevant path immediately.",
156
+
lead: "A service catalog gives developers a browsable home for all paths.",
157
+
text: "Tools like Backstage or Port let each path have a card with a description, use cases, getting-started link, and owner contact. Developers searching for \"create a new service\" or \"set up monitoring\" find the relevant path immediately.",
151
158
},
152
159
{
153
160
lead: "Decision trees help when multiple paths might apply",
@@ -171,16 +178,22 @@ Path discovery also means knowing when __not__ to use a path. Decision trees sho
171
178
The __entrypoint__ is how developers discover and start using the path. This could be a CLI command (`platform create service`), a template catalog in Backstage, or a GitHub template repository. The entrypoint should be obvious and frictionless — if developers can't find the path or the first step is confusing, they won't use it.
172
179
173
180
<List
174
-
variant="check-icons-list"
181
+
variant="chevron-list"
182
+
classes={{
183
+
wrapper: "sm:mr-6 mb-6",
184
+
}}
175
185
items={[
176
186
{
177
-
text: "The core journey is the sequence of steps that gets developers from \"I need a thing\" to \"I have a working thing.\" For a service creation path, this might be: scaffold the service skeleton, configure service-specific values, provision infrastructure, and verify everything works. The core journey should be fast (10 minutes or less for common cases) and should handle the common case without requiring decisions the developer isn't equipped to make.",
187
+
lead: "The core journey takes developers from need to working artifact.",
188
+
text: "For a service creation path, this might be: scaffold the service skeleton, configure service-specific values, provision infrastructure, and verify everything works. The core journey should be fast (10 minutes or less for common cases) and should handle the common case without requiring decisions the developer isn't equipped to make.",
178
189
},
179
190
{
180
-
text: "Extension points are places where teams can customize the path without forking it. These might be pre/post hooks in a pipeline, config overrides, or plugin systems. Good extension points let teams add behavior without modifying the core path.",
191
+
lead: "Extension points let teams customize without forking.",
192
+
text: "These might be pre/post hooks in a pipeline, config overrides, or plugin systems. Good extension points let teams add behavior without modifying the core path.",
181
193
},
182
194
{
183
-
text: "Escape hatches are documented ways to leave the path entirely when it doesn't fit. These should be visible (not hidden), have clear processes, and ideally include a migration path back to the golden path later.",
195
+
lead: "Escape hatches provide a documented way off the path.",
196
+
text: "They should be visible (not hidden), have clear processes, and ideally include a migration path back to the golden path later.",
184
197
},
185
198
]}
186
199
/>
@@ -286,7 +299,7 @@ Escape hatches are how teams leave the golden path when they have a legitimate r
286
299
Four principles guide escape hatch design:
287
300
288
301
<List
289
-
variant="check-icons-list"
302
+
variant="side-by-side-list"
290
303
items={[
291
304
{
292
305
lead: "Documented, not hidden",
@@ -312,7 +325,7 @@ Four principles guide escape hatch design:
312
325
Not all deviations are equal. A tiered system helps teams understand the implications:
313
326
314
327
<Table
315
-
variant="vertical-column-delineation-table"
328
+
variant="numbered-review-table"
316
329
content={{
317
330
figure: "Escape hatch tiers with escalating process and decreasing support.",
318
331
thead: {
@@ -321,19 +334,19 @@ Not all deviations are equal. A tiered system helps teams understand the implica
321
334
tbody: {
322
335
tr: [
323
336
{
324
-
th: "1: Extension",
337
+
th: "Extension",
325
338
td: ["Custom CI steps, extra K8s annotations", "Self-service, no approval", "Full support"],
326
339
},
327
340
{
328
-
th: "2: Override",
341
+
th: "Override",
329
342
td: ["Custom Dockerfile, alternative test framework", "Document in README, async review", "Best-effort"],
@@ -394,7 +407,10 @@ The best golden paths don't need enforcement. Developers choose them because the
394
407
Four incentive strategies drive sustainable adoption:
395
408
396
409
<List
397
-
variant="check-icons-list"
410
+
variant="numbered-with-background-list"
411
+
classes={{
412
+
wrapper: "sm:mr-6 mb-6",
413
+
}}
398
414
items={[
399
415
{
400
416
lead: "Intrinsic value",
@@ -406,7 +422,11 @@ Four incentive strategies drive sustainable adoption:
406
422
Measure this by comparing time-to-first-deployment for path users vs. manual setup, tracking developer satisfaction surveys, and monitoring support ticket volume.
407
423
408
424
<List
409
-
variant="check-icons-list"
425
+
variant="numbered-with-background-list"
426
+
startNumber={2}
427
+
classes={{
428
+
wrapper: "sm:mr-6 mb-6",
429
+
}}
410
430
items={[
411
431
{
412
432
lead: "Network effects",
@@ -422,7 +442,11 @@ Measure this by comparing time-to-first-deployment for path users vs. manual set
422
442
The operational benefits are particularly powerful because they compound over time. A team that's been on the path for a year has gotten dozens of automatic security patches, while a team off the path has been doing that work manually (or not at all).
423
443
424
444
<List
425
-
variant="check-icons-list"
445
+
variant="numbered-with-background-list"
446
+
startNumber={4}
447
+
classes={{
448
+
wrapper: "sm:mr-6 mb-6",
449
+
}}
426
450
items={[
427
451
{
428
452
lead: "Organizational recognition",
@@ -436,7 +460,7 @@ The operational benefits are particularly powerful because they compound over ti
436
460
Some tactics look like they'd drive adoption but actually backfire:
437
461
438
462
<List
439
-
variant="check-icons-list"
463
+
variant="zebra-list"
440
464
items={[
441
465
{
442
466
lead: "Shame dashboards",
@@ -466,7 +490,7 @@ Some tactics look like they'd drive adoption but actually backfire:
466
490
There are legitimate ways to encourage adoption without coercion:
467
491
468
492
<List
469
-
variant="check-icons-list"
493
+
variant="zebra-list"
470
494
items={[
471
495
{
472
496
lead: "Opportunity cost visibility",
@@ -496,7 +520,10 @@ Remember the autonomy spectrum: we're aiming for high consistency __and__ high t
496
520
### Four Categories of Path Metrics
497
521
498
522
<List
499
-
variant="check-icons-list"
523
+
variant="timeline-list"
524
+
classes={{
525
+
wrapper: "sm:ml-6 sm:mr-12 mb-6",
526
+
}}
500
527
items={[
501
528
{
502
529
lead: "Adoption metrics",
@@ -520,7 +547,7 @@ Remember the autonomy spectrum: we're aiming for high consistency __and__ high t
520
547
### Leading vs Lagging Indicators
521
548
522
549
<Table
523
-
variant="vertical-column-delineation-table"
550
+
variant="criteria-highlight-table"
524
551
content={{
525
552
figure: "Leading and lagging indicators for path health.",
526
553
thead: {
@@ -578,7 +605,7 @@ Golden paths aren't static. They have lifecycles — they're born, mature, and e
578
605
Every path moves through four stages:
579
606
580
607
<List
581
-
variant="check-icons-list"
608
+
variant="numbered-with-background-list"
582
609
items={[
583
610
{
584
611
lead: "Incubation",
@@ -604,7 +631,10 @@ Every path moves through four stages:
604
631
Deprecation announcements need to be comprehensive and actionable. A good deprecation communication includes several elements:
605
632
606
633
<List
607
-
variant="check-icons-list"
634
+
variant="timeline-list"
635
+
classes={{
636
+
wrapper: "sm:ml-6 sm:mr-12 mb-6",
637
+
}}
608
638
items={[
609
639
{
610
640
lead: "The what and why",
@@ -666,7 +696,10 @@ A healthy platform team needs several distinct roles, though in smaller organiza
666
696
How platform teams interact with product teams determines whether paths feel like services or mandates:
667
697
668
698
<List
669
-
variant="check-icons-list"
699
+
variant="timeline-list"
700
+
classes={{
701
+
wrapper: "sm:ml-6 sm:mr-12 mb-6",
702
+
}}
670
703
items={[
671
704
{
672
705
lead: "Regular touchpoints",
@@ -731,10 +764,10 @@ The key principles are straightforward: design escape hatches as first-class fea
731
764
732
765
The platform team's job is to make standardization the path of least resistance. When you succeed, shadow infrastructure disappears because there's no reason to build it. Teams adopt standards voluntarily because the alternative is more work. Maintenance burden shifts from every team to the platform team, who can invest deeply in getting it right.
733
766
734
-
This approach requires more upfront investment than mandates. You have to build something worth using, not just declare what's required. You have to listen to feedback and iterate, not just enforce compliance. You have to prove value with data, not just assert it with authority.
735
-
736
-
But the payoff is a platform that developers trust and willingly adopt. And that voluntary adoption is both the goal and the measure of success.
737
-
738
767
<Callouttype="success">
739
768
A successful golden path doesn't need enforcement. When developers voluntarily choose your path because it's faster, easier, and better supported, you've built something valuable. That voluntary adoption is sustainable in a way that mandates never are.
740
769
</Callout>
770
+
771
+
This approach requires more upfront investment than mandates. You have to build something worth using, not just declare what's required. You have to listen to feedback and iterate, not just enforce compliance. You have to prove value with data, not just assert it with authority.
772
+
773
+
But the payoff is a platform that developers trust and willingly adopt. And that voluntary adoption is both the goal and the measure of success.
0 commit comments