Any discussion on platform engineering and platfor...
# platform-blueprints
r
Any discussion on platform engineering and platform development tends to mention the idea of "thinnest viable platform". This is usually followed by the suggestion that your IDP can be as simple as a set of wiki pages. I'm curious: are there specific practices and tools that helped your team start with simple documentation as your platform v0? How did you measure success? Posted in #general
e
We actually followed this pattern initially when we rolled out Backstage. This was a cheap investment. All data we had elicited suggested that discoverability of documentation was a bigger problem than lack of documentation. Because of this, our initial efforts focused on exactly that. That built a solid foundation and trust as well as started to provide a solid feedback loop that we build on thereafter. Documentation can be a great first iteration to self-service, but it is useless if nobody can find it.
r
Thanks! That is exactly my main concern about starting out with docs. It's hard to find where the relevant things are. I've also spoken with another platform engineer whose team use Backstage mainly for docs (for now). How's your experience with it?
Does it allow your team to innersource the docs?
e
it has added a lot of visibility to the docs, and therefor the gaps. We have actually tracked the rate of documentation increase per entities and components as well.
TLDR: It has created a wave of momentum around documentation that has naturally spread across teams
r
Cool. I think I'll try playing around Backstage this weekend to see what it's like.
e
There system with TechDocs is convenient and we tapped into this in a standardized way that allowed our teams to not have to think too much about it.
r
Thanks. Any interesting feedback from the devs using your platform?
e
We have had a lot of positive feedback. I think early on it wasn’t clear the value of it outside of the teams building it. Especially when we talked about it being so much, but at the time just being documentation. Once we started to extend it and offer more self-service is when people started to engage more. We collect a good amount of data as well to track how people are using it.
r
I struggle to think of what kind of metrics you can gather from people consuming docs, which I imagine are static pages. Did you simply measure the traffic going to each page, or did you put some clever instrumentation? Was this something built into Backstage?
e
One hidden detail is that the company we work for Quantummetric.com allows us to add some really interesting telemetry to our backstage instance with almost no effort. This included auto instrumentation as well as session replay. This has allowed us to derive some interesting metrics such as the following: • Documentation Hit Rate - the amount of documentation searches in backstage that led to a result being clicked. • Journey Mapping - We can see the path that people take through our platform to documentation and other tools. • Search Hit Rate - amount of searches resulting in clicked results • Document Rate - the ratio of entities to documentation per group/org/etc. • etc
r
That is SO COOL! Thanks for sharing all that. Really appreciate it.
I particularly love the journeys feature. What tools/plugins did you use to accomplish this?
e
Nothing outside of instrumenting with Quantummetric.com (selfless plug)
r
Interestingly, my team is looking into visualisation and definitely bookmarking this.
You should present this specific story in one of the weekly meetups!
e
Session replay is always beneficial because we can go back and validate patterns if needed
r
Whoa! That's really handy. I love how just through documentation, you can extract important data about developer experience.