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>
This essay is taking some serious time - both in terms calendar duration but also of active consideration. Not necessarily a problem in itself ("Pain is temporary, glory is forever!"), but to outline how I could approach this, some aspects I have considered:
- Spotify Golden Paths, Techdocs, Backstage and Engineering Culture
- Docs Like Code
- The venerable challenge - Information vs Attention
- DevOps and Git - Disruption and democratization
- Communicative developers, Tech-savvy Writers (and User participation)
- Purposes and formats of communication
- Open vs Proprietary - Making do despite insufficiencies
Illustration of: Technical writers, developers, product owners, operations, users, system, internal and external information
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)
Tony R. Hoare 1980 ACM Turing Award Lecture "The Emperor's Old Clothes" - on the importance of ubiqutously palatable communication throughout an organization
The C4 model for visualising software architecture - Context, Containers, Components, and Code
Fragile "lazy dogs" and the Chernobyl test procedure
https://en.wikipedia.org/wiki/Children_of_Dune
https://dune.fandom.com/wiki/The_Golden_Path
https://medium.com/startup-by-design/goldenpath-156c1ff291ab
https://en.wikipedia.org/wiki/Tutorial
https://en.wikipedia.org/wiki/Knowledge_base
https://en.wikipedia.org/wiki/Technical_communication
https://en.wikipedia.org/wiki/Documentation
https://en.wikipedia.org/wiki/Knowledge_management
https://en.wikipedia.org/wiki/User_guide
https://en.wikipedia.org/wiki/How-to
https://en.wikipedia.org/wiki/Community_of_practice
https://en.wikipedia.org/wiki/Knowledge_broker
https://en.wikipedia.org/wiki/Personal_knowledge_management
https://en.wikipedia.org/wiki/Knowledge_worker
https://en.wikipedia.org/wiki/Intellectual_capital
https://en.wikipedia.org/wiki/Knowledge_sharing
https://en.wikipedia.org/wiki/Procedural_knowledge
https://en.wikipedia.org/wiki/Software_documentation
https://en.wikipedia.org/wiki/The_Mythical_Man-Month
https://en.wikipedia.org/wiki/Hofstadter%27s_law
https://softwareengineering.stackexchange.com/questions/9885/how-much-documentation-is-enough
Designing organizations for an information-rich world
https://store.xmlpress.com/product/conversation-and-community/
Videos:
- 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