Documentation Is More than Your Thinnest Viable Platform
As you look to abstract out cross-organizational complexity, team topologies would have you kick off your platform engineering journey with the thinnest viable platform. “This ‘TVP’ could be a wiki page,” said co-author Matthew Skelton in the intro video, or a platform could be as simple as documenting key things like: “We use this cloud provider. We only use these services from the cloud provider. Here’s the way we use them.”
This may not be where your internal developer platform (IDP) ends, but, more often than not, documentation is where it should begin. These “docs” record the most common software development processes and can — probably should — include anything and everything from: how to do X at this company, to error codes and definitions, to the context behind why technical decisions were even made. Docs increase self-service and decrease the internal customer support for your platform. Docs explain who does what. Docs allow people to learn about and then onboard to your platform. Docs teach newcomers how to fish. And docs market your platform to your internal customers.
In fact, according to the 2021 State of DevOps, it’s proven that teams with good documentation deliver software faster and more reliably than those with poor documentation. Similarly, GitHub’s 2021 State of the Octoverse uncovered that developers see about a 50% productivity boost when documentation is “up to date, detailed, reliable and comes in different formats.” And, in this year’s State of API Report, more than half of the developers surveyed cited a lack of documentation as the biggest obstacle to consuming APIs — which is the common way to access a platform.
Whether it’s your first step and thinnest viable platform or you hire a technical writing team to really dive deep, documentation is absolutely a critical part of your platform strategy. Read on for everything you need to know before tackling the documentation for your internal developer platform.
Documentation Enables “Stigmergy”
“The best way to build a platform is through documentation,” argued Kristof Van Tomme, cofounder and CEO of Pronovix, a developer portal specialist consultancy that builds open source developer portals. Pronovix also organizes the DevPortal Awards and the API the Docs conference.
“Spotify has this concept of the golden path, which is basically: What is the best way to do X in our company?” Van Tomme offered his definition of an internal developer platform as “creating shared infrastructure that is better maintained and centrally maintained, that facilitates the implementation of certain downstream stuff.”
Of course, the idea of an internal platform isn’t new, it’s just been historically very top-down. “A lot of platform initiatives go wrong,” he continued, when you just tell a platform team to go build a “platform.”
Golden paths to Van Tomme are akin to the natural phenomenon of stigmergy. When a creature like an ant finds food that it brings back to the anthill, it leaves a pheromone trail to signal to other ants where the food was. The more ants that follow that path, the heavier that pheromone trail gets, enabling contextual learning. The queen or queens have a specialized role, but it’s not to be the boss. In ant colonies, the decision processes emerge because of evolved behavioral patterns that, together with information stored in the environment, enable systems and processes that are both adaptive and resilient.
Documentation fulfills a similar role for an organization as a stigmergic signal. And, he argues, a technical writer will be best suited to document these paths and then merge them together in a way that makes things easier for developers.
“I think that the best way of building platforms is where you are trying to get people to agree on things, but not by forcing them to do things in a certain way because that normally doesn’t work, [and] it’s not a very healthy way of doing things,” he explained. If a platform team is going to remove some developer autonomy and choice, then you’d better “make it the most obvious path, make it easier to follow the right path. And that’s through documentation.”
Docs Help Scale Your Platform’s Scope
Van Tomme reflected on a conversation he had, on the API Resilience podcast, with Jabe Bloom, chief sociotechnical officer and founder at Ergonautic. Bloom talks about how there are three economic models that teams can work under that explain how a platform works:
- Differentiation: create variety and value that customers want to pay for.
- Scale: decrease variability to increase efficiency of used resources
- Scope: create reusable building blocks that couple the economies of differentiation and scale.
Most companies only focus on differentiation and scale.
With a platform strategy focused on scope, Bloom said, organizations can unlock reusability and resiliency, which in turn allows teams to offer differentiating value faster, at scale. “Some things cannot be over-consumed and actually increase in value as they’re consumed,” Bloom explained. Orgs must lower barriers to accessing these things, as “ways of unlocking a huge amount of value in assets and resources that your organization already has.”
In fact, Van Tomme explained, these reusable assets then become better from reuse and the overall reduction of variety and complexity. He said, “You’re trying to build these assets that sit in the middle that help you to have certain ways of doing things like certain jobs to be done, that you’ve replaced by like a building block that makes them simpler to do.”
The best way to achieve this scope? Van Tomme says it all starts with technical writers on an anthropological pursuit to discover if there’s already a golden path emerging in your org.
“It’s documenting what people are already doing. So go and investigate what are the common jobs that you’re trying to build a platform about, then document those,” he said. “By documenting it, you’re actually creating that stigmergic path. Because now, when somebody goes looking for, like ‘how to do Kubernetes at my company,’ actually, there’s an article about that.”
The key is that your documentation is discoverable, he continued, especially for onboarding.
“The golden path is this way of thinking where you utilize documentarians to create an easier route to do common, important things. And then you also make some sort of commitment that ‘OK, if you follow this route, then actually you don’t have to do support on your own. We’ll take responsibility for supporting the building block,” Van Tomme said. Then, later, you can extend the platform to include technology to make those repeat processes even easier, as well as to unlock other benefits like compliance and FinOps.
Before hiring a platform engineer — or renaming a sysadmin or DevOps engineer — Van Tomme recommends hiring a technical writer, who not only curates the documentation but does the necessary internal user experience research. This is a stark alternative to the common practice of having only engineers on a platform team, as they often have the habit of thinking they know what’s best for other engineers.
How to Get Started with Your Platform Documentation
While documentation is meant to suit the needs of your particular customers — which, with an internal developer platform, are likely your engineering colleagues — there are certain must-haves:
- Keep it simple and to the point.
- A step-by-step getting started guide.
- Searchable – self-service is key, even if it’s just via command+F to start.
- Be specific to the user(s).
- Kept up to date with versioning.
- Interactive language, like “you.”
- Filled with examples.
- Error codes and definitions.
- Pathways for feedback and even ways to contribute.
- Clarify what isn’t supported.
Also, remember that for internal documentation, it needs to be useful, but not necessarily polished like externally branded docs would need to be. This makes it quicker and cheaper to do different kinds of knowledge sharing:
- Written: the most common but not the only way. Again, it must be easily searchable.
- Video-oriented: demos and feature releases can be welcoming and casual. Do always have subtitles.
- Generative AI for platform engineering: the price keeps going down, so you soon will be able to leverage generative AI both to create docs and to respond to developer queries in natural language.
“The point is it should allow people to self-serve and the more constructive it is, the better,” Ben Wilcock, technical marketing architect at VMware, told The New Stack. “You also need marketing alongside your platform,” always working to answer the question: “How do you get people to like this thing and respect it and use it and tell other people to use it?”
Your documentation can also act as internal marketing, he continued, including what your platform does, how a feature works, which button to click and which pattern to follow. It can include what he called “creative variabilities” to the most common golden paths.
Documentation can also add context, which will be very different pre- and post-platform. Pre-platform might even be pre-DevOps or still on monolithic architecture, Wilcock reminded us, which makes running and supporting in production very different than, say, containerized and in the cloud. Platform documentation should ease that context switching, making it easier for developers to access deep work.
An area Wilcock said must be documented is the modernization of workloads. “You need a decision tree for modernizing these workloads into the cloud. How do I go about making a decision? Do I containerize? Run it in a special part of that cloud? A decision tree in itself is documentation” and can even include a scoring mechanism to decide where a workload should go.
With a tool like VMware Tanzu Application Platform, he explained, “You can essentially take the essence of something and turn it into a template and offer that template for users to solve particular problems very quickly.” This could include a code generator, plus database access, plus access to other libraries, “gathered together in a recipe book,” including the step-by-step clarity of what’s happening automatically behind the scenes.
You might have a library of ready-made templates in a git repository, which a development team can add to via pull requests, which then the platform team can review, version control and maintain any necessary separation of concerns — and, of course, update the docs. Also remember, architects and developers in different groups may require different standardization around microservices or preferences of different internal libraries.
When looking where to start documenting developer pains, Van Tomme echoes Wilcock by pointing to the popular troublemakers of setting up Kubernetes clusters and creating containers.
In general, as a platform tries to sell colleagues on a certain path, it’s important to include why certain toolchains or workflows were chosen in the first place, both within the documentation and in communicating new platform features. And it’s crucial to gain fans early on in order to uncover platform success stories you can use to onboard more teams.
Just be cautious not to make a garbage list, warned Van Tomme, where you dump everything into your docs — don’t distract devs, make it easy for them to stay on your own golden path.
Innersourcing with an Open Source Mindset
Open source and platform engineering have a lot in common:
- You can’t (usually) force people to use your technology.
- You can’t (usually) force people to contribute to your technology.
- You have limited resources and can’t afford to waste your time providing support, especially for repeat requests.
- You need to create a positive, self-service experience that makes them want to use it.
- Documentation is usually both severely lacking and extremely necessary.
Indeed, while the sociotechnical discipline of treating your platform as a product is still rather nascent, there’s a lot of lessons that can be carried over from open source communities.
“A good product is sometimes only good for the person that builds it,” Precious Onyewuchi, a freelance technical writer including for the CHAOSS project, told The New Stack. “You may have made something really important or useful but there’s no way for people to figure out how to use what you’ve built,” without strategic documentation. She continued that platform teams need to offer a “breakdown of what the product or projects are about, so I can have context of what it’s supposed to do for me.”
Another shared challenge in both multinational organizations and open source projects is that teams scale to the point you lose insight into who does what, she reflected. A platform’s documentation shouldn’t just tell the what but the who — with clear points of contact both for the platform team and for anyone else that could be a barrier (even unintentionally) to release.
And never assume you know your audience and its knowledge level, Onyewuchi added. After all, a lot of your developers may have no prior knowledge of infrastructure, containerization or the cloud. Ask for feedback and also explain as much as you can.
“For open source documentation, one of the core problems is that whoever is in charge of documentation, they don’t get to be on the team easily,” and can feel out of the loop, she said. It’s essential that the platform strategy as a whole and the platform docs are in tight feedback loops with your internal developer customers — and quickly reflect changes and new golden paths.
In the end, innersourcing — the act of allowing people within your company to contribute to shared resources — offers a great way to enrich your platform documentation. It just can’t be done willy-nilly. Organization and search-ability are essential, with a product owner, not just of the platform but of the documentation.
Presenting an easy way for colleagues to participate in the creation of your platform — including its documentation — will always encourage adoption of your platform. Everything in platform engineering should center on your colleague user-base.
Want to learn more about platform engineering? Pre-register to receive the forthcoming ebook, “Platform Engineering: What You Need to Know Now,” sponsored by VMware Tanzu.
