"Yes, but how do you measure success?"
This is easily the most common phrase thrown around, not just in Developer Relations or Developer Experienc...
For further actions, you may consider blocking this person and/or reporting abuse
Hey, This is super useful! :) Definitely interested to know more of your thoughts on "Zero search results, search term keywords" too :)
+1 Vote here also.
Same.
+3!
Great Read. It really saddens me to see supposedully great dev API's that are poorly documented but the core team flaunts it as if everything is super-ready for usage. While from a dev's point of view and experience - that lib/api isn't ripe enough for usage.
Thank you!
Some of this is truly tech debt, they built a great API, they know it very well because they are so close to it, then they have a hard time documenting it because they waited until it was "done" to do so. It can be hard to put yourself in the mindset of the API consumer when you are the API maintainer. Similar analogy to a backend dev trying to explain a frontend experience. The fundamentals might be there, but there are nuances that will impact the experience.
I didn't mention it here, but I strongly believe a dedicated technical writer should be included early in the lifecycle to help design an experience that can be well documented.
We actually had a feature that was going to be released out of lock-step with our product. It was going to be incredibly difficult to document and even hard for developers to understand. Thankfully the release was pushed, but this is a great example of something that should be caught by someone thinking about the documentation experience, whether it's a technical writer or a developer experience professional. We want the experience with the new feature to be good, or as you put it, ripe for usage!
I wonder what could motivate and drive founders of startups and engineering managers to utilize a tech writer or dev experience proffesionals early on.
What is your take on those 2 differnt paths and the importance of proper docs in each?
Outward-facing APIs that generate revenue will always be the easier case because it feels like you can directly attribute dollars lost/gained to the overall developer experience, including docs.
I worked in Enterprise IT and there was no concept of an internal technical writer. The team that built the project wrote just enough documentation to train the support team in maintaining it after a hand-off.
Two things could happen here.
The original project team could face a number of escalations from support (often due to the support team not understanding the project codebase or not having the proper skills to maintain the code base). This would typically hurt the project team more than the support team and result in a re-architecture or redesign of the project rather than a review of supporting assets like documentation, or lack thereof.
Alternatively, the support team could request additional training or a longer hand-off, blocking the project team from moving to the next project. This would usually result in the team leads or the most empathetic members of the team pulling together training. Could it still end in the above scenario? Yes. But often with training came tons of documentation and the number of escalations scaled at a slow enough rate a revamp of the project seemed to make more sense (changing business needs, chance to upgrade tech stack, implement new security features, etc.).
What I would rather advocate for is including technical writing and developer experience earlier in the design process. Stop waiting until a code freeze at the end of your release cycle to write your docs.
Just like you would get a UI mockup early on, why not discuss API scheme design, terms used in the API and product for consistency and clarity, etc. Theoretically, this should be part of UX, but having a dedicated stakeholder participating in design time on behalf of the developer community, the less complex developer experience technical debt you should incur, including docs.
Hi Amara,
Thanks a lot for this article. There's so little content out there still discussing the practicalities of DX work.
We've been scrabbling trying to see what insight we can get from metrics - there's a deep desire to be data-driven in our approach, but a dearth of useful data. Particularly gathering DX data for internal platforms seems to be quite a lot more difficult than for external facing systems. The number of customers is so much lower and it lends itself more to direct contact that objective measures of behaviour.
In that context some of your ideas here are exactly where we ended up, we're specifically restructuring our documentation to provide more direct answers to the "how do I?" questions and trying to establish a pipeline from support requests to documentation solutions (as well, as code solutions, of course).
It is deeply gratifying to see others coming to similar conclusions and to increased the shared knowledge in this space.
I love the idea of internal developer tooling teams, but I wondered if exactly what you mentioned was going to be a problem.
Even documentation seems silly to take a data-driven approach. All documentation, particularly externally facing documentation, is a value-add to the business.
Another option for internal is how fast or how friction-less onboarding developers is. Could be new developers, junior devs, or if you run some kind of rotation. Are you scoping or sizing less time/effort to onboard?
Funny you should mention that - onboarding time/complexity is our most pressing issue right now. Documentation is part of the problem, but automation is a bigger one. Setting up DX as a function and taking responsibility for discovering and fixing these kinds of problems is, in and of itself, the closest thing to a silver bullet.
FWIW, this is my second internal DX role (we actually called it DevCare last time around) and it's fair to say that the problems are quite different, as are the organisations. It strikes me that the way of thinking and the ownership of the domain are what matter most.
This is a really cool and thoughtful article - thanks for laying it out so nicely Amara. I always just think about my own documentation for design stuff and the scale of that with maybe like 20 devs/QAs max. Looking at it in this context, I'm mind blown, of course when things scale for larger teams and sharing across internal and external groups documentation quality/measuring etc become such a big deal.
The time wasted answering the same things again and again that could be a link to a Single Source Of Truth, could be an addition to metrics like number of questions but without a holistic view you won't go very far.
However, the ability to track the success of documentation might motivate some people who find it as the most boring thing on Earth LOL!
Love your focus on impact and not the 'easiest to measure' vanity metrics that so many of us get caught up on.