Sequence: Zen and the Artwork of Bike Upkeep
On this episode, I chat with Dan Grabski, a senior content material developer based mostly in Portland, each about his latest WTD speak titled ‘Zen and the Artwork of Manually Creating API Documentation’ and Robert Pirsig’s ‘Zen and the Artwork of Bike Upkeep.’ Dan explains the significance of focusing not simply on technical particulars of implementations but additionally on integrating the folks facet — on understanding the views of various customers and stakeholders concerned. Dan gives examples from his engineering background as an example how instinct develops from expertise, how you can keep away from spectator mode via hands-on exploration of APIs, on carving out time to commit to continuous studying, and the worth of incremental progress. Total, it is a terrific dialog about partaking extra deeply with know-how to put in writing higher documentation.
You may view Dan’s Write the Docs 2023 Portland speak right here: Zen And The Artwork Of Automanually Creating API Documentation – An Inquiry Into Course of. It’s also possible to observe Dan Grabski on Linkedin.
You may view a literal transcript within the YouTube model. The next is a extra readable model of the transcript:
Tom: Welcome to a different episode of the I’d Slightly Be Writing podcast. I’m Tom Johnson and I’m speaking right now with Dan Grabski, a technical author in Portland with an fascinating background. We’re going to be speaking about a number of the subjects in Zen and the Artwork of Bike Upkeep by Robert Pirsig, in addition to Dan’s speak at Write the Docs that adopted related themes.
So Dan, earlier than we bounce in, are you able to introduce your self a bit — the place you’re based mostly, what you do, and who you might be?
Dan: Thanks for having me on, Tom. My identify is Dan Grabski. I’m based mostly in Portland, Oregon within the stunning Pacific Northwest. My unique background is definitely in mechanical and electrical engineering — I went to the College of Rochester and received levels in these fields. I labored in skilled motorsports for about 10 years. I used to be in IndyCar racing, lived in Indianapolis for some time, did engineering with groups, traveled around the globe.
When the financial system went downhill in 2009, I had some mates dwelling in Portland and moved out right here. I ended up making the bounce to the semiconductor trade, the place I used to be nonetheless doing engineering however did increasingly more technical writing. I went via a pair different jobs and most lately I’ve been working in fintech. For about two years I labored as a software program engineer, and a couple of yr and a half in the past I transitioned to affix our tech content material group as a technical author whereas nonetheless retaining a number of the software program engineering work I had been doing. So I’ve received a foot in each worlds, so to talk.
Tom: You actually do have an fascinating background. I assumed you’d be the right particular person to speak to about this subject since you clearly have a mechanical engineering background and software program growth mindset. I don’t even know how you can describe what I used to be attempting to say, however you’re used to engaged on issues.
The speak you gave at Write the Docs in Portland in 2023 was titled Zen within the Artwork of Automanually Creating API Documentation: An Inquiry into Course of. I didn’t make it to the final Write the Docs convention, so I used to be simply listening to the recordings. This one actually jumped out at me — you’re a terrific presenter, so it was very straightforward to observe your practice of thought and perceive.
Are you able to inform us a little bit about that presentation — what was your major level or argument?
Dan: The key that’s probably not a secret is that it was really my first convention presentation too. So it was nonetheless one thing new, however I received to lean on different experiences I’ve had.
The actual core of what I used to be getting at is that there’s lots of give attention to the technical bits of how we are able to mechanically create API documentation — what instruments and software program we have now that may do that for us. However there’s not as a lot perception into how it will work together with the folks all through the method.
You’ve received software program engineers writing specs, product managers, coders, technical writers, and finish customers. A variety of Zen and the Artwork of Bike Upkeep delivered to thoughts for me is that there actually is a relationship between the technical points and having a deeper understanding of how we’re interacting with it — what’s the premise of that interplay and the technical facet.
It feels prefer it’s simpler to get a deeper understanding so that you don’t simply have that floor stage perception anymore. You may perceive that this documentation is being utilized by a software program engineer with 20 years expertise or guys in a strip mall workplace beginning their first startup who’ve by no means seen code earlier than. It could actually actually run the gamut, and having that perception helps you tailor the documentation. It additionally hopefully allows you to be extra agile and sustain with modifications extra simply.
Tom: You’re saying you actually wished to give attention to the precise folks utilizing the API, not simply the technical technique of publishing it. You have been speaking about totally different consumer sorts and inside processes in addition to exterior customers, proper?
Dan: Sure, and I introduced up this instance — in an expert scenario you generally really feel such as you’re speaking previous one another. You assume the opposite particular person isn’t understanding, they usually say you’re not understanding. It’s not that folks aren’t understanding one another, it’s simply that they’re targeted on totally different values.
The technical deserves of either side of the argument could also be sound, however that doesn’t make it simpler to speak about generally. Having the ability to step again a little bit and perceive your undertaking supervisor has one set of values, a software program engineer one other set, a supervisor one other set — it helps to tailor your message to totally different folks.
You’re not attempting to tug one over on any person, you’re attempting to deal with their values immediately. That perception no less than helps you tailor the documentation, and hopefully allows you to be extra agile.
Tom: I like that viewpoint of getting all these totally different views occurring, and totally different folks see issues in a different way. There’s not only a single path via a subject.
Did you reread Zen and the Artwork of Bike Upkeep earlier than your speak, or was this a e book you’d learn way back that got here to thoughts if you have been excited about this stuff?
Dan: I had learn bits of it a very long time in the past however by no means sat down and went via the entire thing. Write the Docs was going to be shut, only a couple miles from my home. I actually awoke one morning and thought “Perhaps I can do a chat on this.”
I sat down and browse via my copy, taking a bunch of notes. I want I may say it was this lengthy journey to search out a tremendous speak, but it surely was a lightweight bulb second — hey, this can be a factor, and it was capable of come collectively fairly effectively.
Tom: Once I was listening to your speak, I used to be excited about after I learn this e book round age 17 after graduating highschool. I had a bike then in order that’s most likely why I began studying it, however I didn’t perceive a lot of it. It’s a protracted 400 web page e book with out a very specific plot — it’s the narrator’s wrestle to reconcile his earlier self together with his present self and his child. There are lots of discussions about high quality, intuitive pondering, and our relationship with know-how. It’s not a simple e book to plow via.
However I like your software of the know-how and folks duality that you simply’re collapsing and displaying integration between. I feel that’s a really sound takeaway. I’m questioning if in case you have any extra ideas on a number of the e book’s themes — what resonated with you that jumps out?
Dan: To again up a bit — it’s a slog to get via and a few components are very dated, like views on psychological well being that we’ve improved on right now. I don’t advocate studying and making use of every thing verbatim to actual life.
You see lots of enterprise books attempting to use Jap concepts to administration in a template, which completely doesn’t work. I feel taking a number of the concepts and looking out via the lens of technical writing is the best way to go.
Early on, the e book talks about his buddy who takes his good bike to the store for any work, as a result of he doesn’t care to determine what’s occurring behind the scenes. Robert Pirsig desires to take it aside and work on it himself. I like the concept dealing with setbacks and issues will get simpler for those who perceive a little bit of the mechanics.
You don’t have to know every thing about carburetors or spark plugs, however figuring out some fundamentals of how a 4-cycle engine works may also help. For instance, you don’t need to put a stainless bolt in a stainless fastener with out lubricant, as a result of it should seize up. Should you perceive these metallic interactions, you may deal with points higher.
It doesn’t provide you with all of the data to repair every thing, however you may deal with extra by yourself and be forward of the sport. Harley homeowners say every thing rattles unfastened finally — you may Loctite bolts and nuts, however for those who don’t assume that’s a problem, components would possibly fly off till your shifter falls off on the freeway.
It’s an excessive instance, however I like bringing that concept of deeper understanding into writing documentation. I handled an API that had nice factual documentation on each endpoint and performance. There have been most likely 20-30 endpoints, however attempting to place it collectively was painful. It felt like a database developer had made it — excellent for a database, however not for me attempting to get knowledge from the service.
I used to be hitting 5 totally different endpoints for what ought to have been a reasonably easy use case. It appeared database-oriented, when actually customers wanted sure knowledge grouped collectively from a consumer perspective. The nuts and bolts of the docs have been wonderful, however not the top objective. Just a little extra thought into the ultimate use would assist.
Tom: There’s quite a bit to unpack there, however one half that jumps out is that this inclination to strive issues your self to deepen understanding. I feel we regularly fall into spectator mode with docs — I’m documenting APIs however by no means calling them or integrating them. I’m simply getting information from engineers and writing it down.
Do you assume to put in writing actually good docs it’s important to use the product, not be in spectator mode?
Dan: I positively assume it’s an enormous assist. On my present group I’m the one developer — the remaining are writers. I’ve been serving to information them to make use of Postman to hit our API. I’m virtually main them via our software program growth onboarding so that they do what a buyer would do.
It’s not the identical as what an engineer would do, however even surface-level understanding and seeing it play out brings perception. In any other case you would possibly spend months writing docs, then study prospects use the API in a different way and must rewrite issues. I like having the ability to see the method play out the best way an finish consumer does. You would possibly notice an endpoint doesn’t have knowledge you anticipated, which is de facto essential.
I’m not proposing writers have to change into builders, however no less than a “trip alongside” with somebody skilled can effectively switch data. In software program, pair programming places folks with totally different expertise collectively — one drives the keyboard whereas the opposite appears over their shoulder. You get actually environment friendly data switch, and technical writers get to see the method like their customers do.
For instance, you would possibly notice you want an authorization token for an endpoint. It doesn’t take an entire lot — simply having the ability to have that floor understanding by seeing it play out might be actually essential.
Tom: You’re making me take into consideration how in lots of circumstances I’ve relapsed into spectator mode. However I’m additionally excited about the e book’s themes of individuals’s relationship with know-how. Pirsig’s buddy John doesn’t need to do any bike upkeep himself, just like a tech author not desirous to study the way it works.
It appears higher for a tech author to not have that mindset — to need to study, strive issues out, and expertise the know-how even superficially. How do folks cross from spectator to tinkerer?
Dan: It’s very robust, particularly with skilled time calls for saying you’ll want to get docs carried out by a deadline, and no straightforward option to carve out time for oblique work.
I keep in mind a superb article referred to as “Being Glue” about unpromoted work — organizing conferences, admin work, interfacing between groups. It’s crucial however not a ticket getting carried out or PR merged, so some say it’s not actual work. I’m an evangelist for making time from the highest down for studying.
I’ve had interns and groups the place I stated let’s block out two hours every week for studying — watch movies on new expertise. It’s foolish it’s important to be draconian about it, however with out that assist it’s troublesome. I took the perspective of “If no one else will do it, I’ll” — be the particular person with sufficient pull to maintain it going regardless of pushback. It’s so crucial, although corporations all the time say they care about skilled growth. Typically coverage and values don’t match up — that’s a crucial hole needing mounted.
If there’s no time for studying, like becoming a member of engineers on a tech days undertaking, it simply doesn’t occur. You must be intentional about it. I acknowledge it’s not an possibility for some corporations, and I need to inform them they want to do that! That’s why I evangelize it, as a result of it’s so essential. You must make intentional time for it.
I feel that’s a terrific level. I attempt to take an hour right here and there to learn paperwork I do know I ought to get to, and find out about a subject. It does present good area.
I feel even when folks purchase into studying and rising, there’s a psychological hurdle of it being painful to study one thing new. My coworker described it as rearranging your psychological furnishings. For instance, I bike to work and was good at adjusting pad brakes by squeezing a cable.
In some unspecified time in the future the trade switched to hydraulic disc brakes, and I didn’t need to study them. There’s a block in me, just like resistance testing an API as a result of it appears tedious and exhausting. One half that resonated with me within the e book is the humorous instance of some bicycle meeting directions that begin by saying you want “nice peace of thoughts” to construct this bike. That peace of thoughts appears mandatory to soak up new issues with out frustration and stress.
How do you get into that peaceable way of thinking that allows pleasant studying?
Dan: Full disclosure — I’ve by no means made the change to hydraulic brakes both! However that’s humorous in regards to the directions requiring peace of thoughts. Partially it’s cultural, however it’s important. You will get offended at know-how, however that gained’t change the way it interacts with you — solely the way you work together with it. Your emotional state doesn’t have an effect on know-how positively or negatively.
But it surely utterly impacts the way you work together with folks, they usually’ll work together in a different way with you based mostly in your emotional state. You’re tailoring your message to what you’re working with — know-how doesn’t have emotions, so being logical and dealing via it helps clean issues out a bit. Getting offended invariably makes your course of much less clearheaded, and issues go extra unsuitable.
It’s actually troublesome to do completely — I nonetheless get annoyed when issues go unsuitable. However taking time to step away and reset is invaluable. Huge change is tough — shifting to a brand new metropolis not figuring out anyone, attempting to rearrange your lounge since you’re annoyed. However you may take the journey in chunks and make it manageable.
It gained’t utterly resolve each downside, but it surely’s a tactic of — how can we break this down into smaller steps? And acknowledging the value of little enhancements — all of us need to make issues higher, not simply whittle away hours. “Don’t let the right be the enemy of the nice” — it’s higher to make small enhancements than get down on your self and make it exhausting.
I like your bringing in of incrementalism. Once I listened to your speak I questioned why you targeted on it. It looks like an Jap concept — gradual, steady enchancment. However I feel it applies to studying troublesome ideas and applied sciences too — spend 20-Half-hour getting acquainted relatively than attempting to cram all of it in at some point. It makes issues extra approachable.
I wished to ask extra about this bigger concept of high quality within the e book. Pirsig maddeningly by no means defines high quality, saying its undefinability is a part of its nature. However my sense is engineers typically proceed intuitively via issues. Like with an API — there won’t be docs, or they won’t be useful. Engineers appear to information themselves with out particular steps, going with the stream. Is that an actual phenomenon or simply my impression?
Dan: With my engineering background, it’s a little bit totally different than software program however related ideas. In college, you are taking lessons on mechanical programs, thermodynamics, and so on to study the constructing blocks for the working world. The fixed joke was that your first job was if you actually began to study engineering.
The intuitive really feel doesn’t simply come out of nowhere — there’s lots of foundational work behind it. Like Pirsig engaged on his bike, he didn’t simply know how you can repair it. For instance, righty tighty lefty loosey — for those who don’t have that fundamental data, there’s no option to develop an instinct of how issues ought to match collectively. There are core ideas, legal guidelines, and guidelines assembled in a means that is sensible for the undertaking.
Once I performed jazz music in highschool, I went to a camp with skilled musicians and we talked about improvising. One sax participant stated he didn’t simply blast into solos — after 50 years, he had “licks” ingrained that he knew to make use of for sure songs and keys. Earlier than going right into a solo, he stated he “programmed the licks into his sax.” The solo was superb, and he broke it down into the constructing blocks he put collectively to make it work.
It takes lots of expertise to construct that instinct. Initially it may be irritating not having that instinct for the way issues work. However over time you achieve constructing blocks, after which at some point you simply know what documentation an API wants that no one else considered due to your expertise. It begins coming along with work — it’s not absolutely inborn with none background.
Tom: I actually like your jazz instance. My daughter performs saxophone, and I noticed the group do an improv session. I wasn’t certain if that they had simply memorized components, however she defined it such as you did — they follow a ton and have sure licks and methods that construct as much as it. It’s reassuring as a result of I feel that’s a extra mature view of the educational course of.
Nicely Dan, we’ve been chatting some time and coated lots of nice subjects. I’ve actually appreciated your perspective, and I preferred your speak quite a bit. I’ll put it within the present notes — any final subjects or sources you need to level folks to?
Dan: The quantity of sources out there’s staggering. I’ve misplaced monitor of what number of instances in an expert surroundings I’ve felt like I used to be speaking previous somebody. Even simply studying fundamental expertise for stepping again and rearranging your preconceptions can deliver lots of worth.
I made a degree in my discuss assuming good religion within the office. I want that have been the case universally, but it surely’s not. We should be aware that persons are appearing in good religion so these instruments will work. If not, which sadly occurs, we are able to attempt to apply the instruments however they gained’t work. That’s not a failing on our half for attempting in good religion — it’s on the opposite particular person.
You will get actually annoyed when that occurs. It does suck. There are different points that include it too. However we’re nonetheless doing our greatest, and possibly we discover a higher surroundings to make use of these expertise. It’s not our failing — we’re doing the very best we are able to.
Tom: I feel these are nice closing ideas. A lot of Pirsig’s discuss bikes applies to understanding ourselves and totally different viewpoints within the office and past. The actual turning level within the e book is when he connects together with his son, speaking brazenly. Your takeaway traces up effectively with the e book’s themes of understanding totally different views. Thanks for approaching the present, I actually appreciated it and I’ll hyperlink to your speak within the present notes.
Dan: Thanks for having me on, it was lots of enjoyable!
About Tom Johnson
I am an API technical author based mostly within the Seattle space. On this weblog, I write about subjects associated to technical writing and communication — equivalent to software program documentation, API documentation, AI, data structure, content material technique, writing processes, plain language, tech comm careers, and extra. Try my API documentation course for those who’re searching for extra information about documenting APIs. Or see my posts on AI and AI course part for extra on the most recent in AI and tech comm.
Should you’re a technical author and need to carry on high of the most recent developments within the tech comm, be sure you subscribe to e-mail updates under. It’s also possible to study extra about me or contact me. Lastly, word that the opinions I categorical on my weblog are my very own factors of view, not that of my employer.