In July 2021, I asked to have a month to strategically think about documentation changes for the product we now refer to as Camunda Platform 8. I was so busy executing on the things that needed to be done that I really didn't have time to think, but at the end of that month I created the Docs Vision that would take us through April of 2022.
I'm already looking ahead and drafting a docs vision 2.0, but I wanted to take some time to talk about the changes we've made as a team to support our technical product documentation.
Creating the docs vision framework
This docs vision was going to be the first formal attempt at bringing an overarching lens to technical product documentation at Camunda. I want to be clear that we had docs before, but the structure lacked strategic direction and nurturing.
To build out this framework I knew I was going to need to include context for what I wanted to achieve and why, as well as the current state of things. We have good docs, had good docs, and will continue to have good docs, but we needed direction and I needed to make sure I garnered as much support as I could along the way.
Setting clear goals
One of the most common pieces of feedback I received about our existing docs was they were filled with a lot of good information, but often lacked how to actually do something.
It was clear our conceptual content was in a good place but we needed to review whether our docs were task or goal-oriented.
Here are a few other goals:
- Camunda Platform 8 documentation should be SaaS-first to match how to intend users onboard to the product.
- There will only be one Getting Started Guide.
- Content will be structured to optimize SEO & UX (less clicks, more keywords).
I'll violate at least one of these goals in the end, but that's another blog topic.
Working in public
Going back to context, I'm the first Head of Developer Experience and (to my knowledge) first DRI (directly responsible individual) for documentation. I was going to get questions about what I was doing and why and I was going to find people who cared enough about documentation that they needed a way to add feedback if they had it.
So before I was even close to finishing a draft of my vision, I provided a link to my WIP docs vision and actively built out a structured presentation with my thoughts as I worked through my ideas.
While I don't know if this worked as intended, I'm pleased to say I often had an answer to questions as they came up rather than after the fact.
An unintended consequence of this was other people across the company did similar things - sharing in-flight draft work. Working in public can be a little nerve racking at first, but incorporating that feedback early and often gives others a chance to feel included and heard.
Low-fi mockups & sitemaps
Easily the most effective piece of my docs vision was the sitemap. This both surprised me and didn't surprise me. I could move whole sections or individual pages across the site easily and without consequences.
My years as a front-end developer told me to keep mockups as basic and low-fidelity (low-fi) as possible but I needed them to describe things like landing pages. While this wasn't as contentious as it could have been, I found myself only ever presenting or talking through the sitemap. Unless I need to convey a specific design choice, I'll likely stick to sitemaps over mockups.
Implementing the vision
I don't want to say I received no feedback while I was building the docs vision, but I received very little. Nearly all of the feedback I received happened very abruptly in Jan 2022 when we completed some of the most significant changes.
For a few weeks, I woke up dozens of Slack DMs, threads, and mentions from various teams across the company DAILY. Had I not been feeling overwhelmed, I probably could have noticed this feedback largely fell into two categories - product feedback (not something I controlled necessarily) and documentation work that was clearly identified in the docs vision (something I not only controlled, but communicated months ago). I'll remember this next time.
Internal and external user behavior
One of the biggest concerns internal folks expressed was moving content to different areas in the documentation. "It doesn't belong there" or "I don't think to look there" was the most common theme.
What I continued to reiterate was this actually wasn't a problem, or rather it was a problem but only for internal employees.
The overwhelming majority of traffic into our docs originated from Google searches, not from folks clicking around in our docs. This behavior inspired the goal around SEO.
I don't want to make things harder for our internal folks, but at the end of the day my priority is enabling external community members. We are still working through making our docs SEO-friendlier. And we are still going to evaluate where things sit in the docs and across the nav. I promise.
Looking back
Our CTO and my skip-level manager, Daniel Meyer, have a bit of a habit of messaging each other "want to see something cool?" and sharing a quick, somewhat random update on something we've worked on recently.
"Look, I actually did what I said I was going to do!!! Isn't that cool?!"
Daniel was the person who initially requested a docs vision, had provided some feedback along the way, but we didn't really have check-ins but he could see progress by looking at the docs site. It was great to share this moment with him.
I'm not really one to brag about myself. It's much easier for me to brag about everyone else on their behalf, but taking a few moments to relive all the feedback and work my team and I completed to achieve the docs vision was the perspective I needed. In that moment I knew it wasn't an accident. We did nearly exactly what I set out for us to do.
"How did you get into docs?" an engineer asked me over Slack a few weeks ago. "I'm trying to correct the experience I had when I was a developer," I said, "I don't want people to struggle to make a product work for them like I had to."
And now I need to write v2. From here, we iterate.
Photo by Matt Noble on Unsplash
Top comments (0)