Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Golden Paths and Knowledge Management from the trenches


Starting from my conversations with SJ and my Underlay Discourse notice "Ideas for community engagement" (a mashup on a Jupyter Binder contraption, Spotify Documentation as Code "Golden Paths" concept and value-based architecture), I was encouraged to write an article/essay/paper/something for KFG Commonplace microjournal on the topic of Golden Paths and "self-documenting solutions".

I find the topic very engaging, and having wrestled with wikis and knowledge management in general, as well as from a bit of research discovering the "documentation as code" concept, I would like to fashion something readable in that domain.

As I just created a pubpub profile, and can't create a commonplace pub (or know where to put it), I'll start typing here. All interaction is welcome.


<define my own golden path through this quagmire>

Scratch notes

The “Spotify Model” (crisp: Scaling Agile @ Spotify with Tribes, Squads, Chapters & Guilds) (PDF), though see the subsequent InfoQ: Don’t Copy the Spotify Model and commentary: SAFe, Atlassian, Jurriaan Kamer / The Ready, Willem-Jan Ageling and Vitality Chicago
Spotify Engineering Culture (Part 1) (Part 2) also as video: Part 1, Part 2. See also Jason Yip, Agile Coach at Spotify
Backstage Developer Portal

happy path: Guidelines + Introduction tutorial + Shared solution collaboration

"Why it takes so long just to put in windows" - not just shoddily built, but you integrate all you've built to date, use it as tools...

Lazy dogs break at the first change of circumstance. Easier to duplicate than to improve.

Guidelines are written as orders, not the best way to do things. Guidelines as documents, not close to developers or validated

Tutorials are not advanced or real

Continuous inexperience?

Knowledge management and technical writers are not domain experts or agile

DevOps makes it everyone's problem

first order - technology enables more information

second order - more information is required to develop technology

Shared solutions lack collaboration structure (inner source)

Best to rely on that people want to do a good job (Teal?)

Open - not reinventing the wheel, interleaving, common knowledge

Development is not stateless, and neither are developers helpless (or ought to be thought of as such)

2020-09-25 The Changelog podcast – Episode #415: Spotify's open platform for shipping at scale with Jim Haughwout and Stefan Ålund

2020-11-19 Software Engineering Daily podcast - Backstage: Spotify Developer Portals with Stefan Ålund

Designing organizations for an information-rich world

2014-09-15 Writing great documentation
2015-05-19 Documentation, Disrupted: How Two Technical Writers Changed Google Engineering Culture
2017-11-09 Documentation as code (explained to my dad) by Hubert Sablonnière
2018-03-08 Writing technical documentation
2018-03-09 Docs as code tools and workflows presentation
2018-03-23 Bryson Tyrrell - Your code should document itself! Embedding documentation into your Python projects
2019-02-27 #CodeTips: What is Self-Documenting Code?
2019-04-14 Building Docs like Code: Continuous Integration for Documentation
2019-10-03 Docs as code | We did it! Didn’t we? • Rafał Pawlicki • soap! 2019
2019-10-23 Building Docs Like Code: Continuous Integration for Documentation
2019-11-26 "Docs as Code - Documentation Management Inspired by Software Development" presented by Alex Jitianu
2019-12-18 Writing effective documentation | Beth Aitman | #LeadDevBerlin
2020-01-13 "A Practical Introduction to Docs-As-Code" - Alec Clews (LCA 2020)
2020-04-01 How we are solving internal technical documentation at Spotify -- Gary Niemen

Perhaps for illustration: 2008-07-06 Pro-Pop and Neo Quad Games Review or 2008-12-03 POP Station Watch 2: GBA SP Rip-Off

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment