A bump in the road of my own journey
I confess – a lot has been going on in my life lately. Upon returning to San Francisco from PyCon, it became very clear that my home situation had become unsafe. One day I’ll write a bunch of achingly beautiful pieces about the experience, but for now, I am focused on persevering through some temporary discomfort while I get myself to the other side of this – step by step, one foot in front of the other.
I considered skipping the DevRel Digest this month, but I know I’ll be disappointed with myself if I miss it, so here I am – better late than never! I’ve hit a bump in the road, but it’s not an obstacle I can’t overcome. However, if the quality is not quite up to par, you know why!
Obstacles in the developer’s journey
Obstacles are something developers are particularly adept at overcoming because our whole job is problem-solving, debugging, and working within the confines of technical constraints. For a developer, an obstacle is an inspiration and the impetus for innovation, and the best among us can zoom out to see the whole picture without fixating too much on the details.
However, while developers are pretty tenacious, nothing detracts more from innovation and efficiency than crummy documentation. As we can see in this diagram of the developer’s journey rendered as a subway map by the DevRel.Agency, documentation – or some form of written direction – is critical to almost every aspect of a product’s relationship with its users.
The developer journey represented as a subway map via the DevRel.Agency
A developer may brute force their way through poor documentation, but why put them through that? Especially when you’re competing with other products and services that do the same thing?
I remember a trip to London when the underground was under major construction. As I listened to the announcement over the loudspeaker about alternate routes, I remember the anxiety rising in me – how the heck was I going to get around? Fortunately, I was out with the friend I was staying with, and he got us home safely, but even he – a resident – struggled to decipher the detours. This was when Google Maps was still rather unsophisticated and rideshare services were nonexistent. (And I’m pleased to share I successfully navigated the subway during my post-PyCon trip to New York!)
Even the best developer is still susceptible to imposter syndrome – don’t let your documentation be the reason they question their competency.
What I love most about this diagram of the developer’s journey as a subway map is the way it illustrates how developers are just trying to get from point A to point B, and how developer relations can provide the path to their destinations. Part of getting developers where they want to go is outlining the steps to get there – a point that Taylor Barnett-Torabi sums up nicely here:
What should I do next?
I wish life had better documentation! I find myself asking, “What should I do next?” with no clear answers more than I would like to these days, but your documentation doesn’t have to be that way! But what happens when your docs fall out of sync? And what are some ways we can fortify our documentation against lapses in accuracy?
I’ve been eagerly watching Manny Silva’s work on documentation for a while now, and his talk at the Linux Foundation’s Open Source Summit has me really excited about the future of documentation. In his talk, Silva outlines the common issues that arise when it comes to keeping documentation and product in sync, as well as demos his own open source solution.
But don’t take my word for it! Check out his talk to learn more!
And now … a tarot card
I apologize for this very light DevRel Digest, but even with everything going on, I wouldn’t leave you without a Gary tarot card.
For this DevRel Digest, I chose the Ace of Wands. As the ultimate representation of the suit of Wands – which symbolize creativity, intuition, and imagination – the Ace of Wands is the fire that guides our way. That’s the purpose your documentation serves: it is the fire of inspiration that guides developers along their journey.
Gary Photoshopped poorly into the Rider-Waite tarot card for the Ace of Wands — no effort was made to incorporate Gary in any logical way
Events and Resources and Other Notable Things
I still work for Streamlit and I am still obligated to invite you to Dev Day – won’t you come? I’ll be there too! Dev Day is June 6th in San Francisco.
PyCon was great and I’ll write more about it later when my brain isn’t so much in survival mode, but for those of you who were asking for the slides, you can find them here! The recording for the talk is coming soon!
And if you’re in the Bay Area, you can just come see my talk live! I’ll be presenting my PyCon talk at North Bay Python at the end of June. Let me know if you plan on attending!
