@Stefan Kolesnikowicz we are very much struggling building the right documentation around our platform. Finding people good at docs is extremely hard! I was also watching your conversation with @Luca Galante, @Jessica Ulyate and @Schuyler Bishop, really interesting. You guys briefly touched on templating but I was wondering whether you had more examples of useful boilerplates you all used to facilitate dev adoption?

Sorry to jump in this thread, but what about training people? Writing good docs is a skill like many others, it can be learned (if people are willing to learn). No amount of templates will turn someone into a great technical writer by itself.

Hey @Terry Davis! I used to work at GoCardless (~700 person fintech unicorn) working on their internal developer platform. One of the biggest things we did to improve documentation, and one I recommend without reservation to people nowadays, is to agree on a structure and create templates for it. The one we use is: https://documentation.divio.com/ We maintained a doc space for all infra tools that split docs by this type, and templates for each different type of doc. It’s a massive step forward for doc-writer (and reader!) productivity, as it avoids the ‘blank page’ problem and helps set guidelines on the type of effort required for whatever you’re writing. It also helps when discussing investment in docs, as you have a shared concept of how much effort should go into a how-to (<1-2hrs) vs a tutorial (days). We use this at incident.io now (attaching a screenshot of our Guides database, which splits docs like this) and the blog post I wrote about our Getting Started tutorial, which links to the tutorial: https://medium.com/gocardless-tech/deploying-software-at-gocardless-open-sourcing-our-getting-started-tutorial-ab857aa91c9e

100% agree, writing is not something you're born with, we all have to practice to get better 🙂 But, what I've found useful is a framework to think about what kind of docs you're writing. The people at my work are all sick and tired of me posting about this Documentation System, but I really love how it breaks down the kinds of docs, when they're applicable, and how they help the reader

I agree 100% with @Manuel Pais (co-author Team Topologies) - I think you need an anchor of the team that’s a senior engineer / staff engineer level and then you can grow the team’s capabilities around documentation from there. In terms of specific methodologies, my team had centered around the concept of Architecture Decision Records (ADRs) where we want to capture snapshots of time that lead to a given architecture. We see these as “git-like” decision histories where the past should be mostly immutable and show you how you got to the present day, what you were thinking, why you decided it, etc. Basically if the entire team is replaced, how can you share context of the what, why and how for a given decision.

I agree that writing is a skill and that it can be learned. With that in mind though, when someone is first introduced to something like software engineering, you get them to start with smaller tasks that have little ambiguity, so they can effectively practice and level-up. If you have agreed doc templates, it means: • Someone can look at existing docs to understand the style of what they’re being asked to write: structure, prose, purpose, length, etc • The template reduces ambiguity, as they can ‘just’ follow the template to write what they need My experience around training writers is the hardest part is confronting a blank page. What do I even say here? What type of content are people expecting? I’d argue templates get people over that cold start and onto the writing content part, and a lot of learnings can only happen once you have someone feedback on what you’re written.

Thanks everyone for the great information. You answered for me :) hahaha We for sure had these problems as well and did what @Lawrence Jones and @Manuel Pais (co-author Team Topologies) mentioned. We had many people problems which are just as hard to solve as technical problems.

Wow, I got so much more than expected! Many great insights. I liked the template example @Lawrence Jones shared. I'll pass it to my team 🙂 And we have tried practising for quite some time, but it appeared that some of our folks just like coding and don't want anything else outside their "comfort" zone 😞

@Terry Davis with the typical “show me the incentives and I’ll show you the outcome” mindset, I’d encourage you to think about what causes people to see docs as a “waste” of their time. If quality documentation is valuable to your org, it’s worthwhile showcasing it and helping praise – visibly! – the people who write it. Couple that with amble sprinklings of “helps empower teams through clear, concise documentation” and you’ll probably find yourself on the other side, trying to prevent people spending too much time writing it.