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>
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
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)
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