Experts from Stripe and Waymo explain how to craft great documentation (Ep. 455)
We chat with Jared Bhatti and Zachary Sarah Corleissen, two technical writers with deep experience at major tech companies and open source projects, about their approach to documentation and the new book they helped co-author, Doc For Devs. We go deep on the best ways to annotate a codebase for future generations and how to localize explainer content so that it works for teams across multiple regions and languages.
If you want to dive deeper, Jared and Zach wrote a blog post for us you can find here.
Episode notes:
Docs for Devs: An Engineer’s Field Guide to Technical Writing can be found here.
Jared worked as a technical writer at Google for more than 14 years and recently transitioned to Waymo, the self-driving car company spun out under the Alphabet umbrella. You can find him on Twitter and LinkedIn.
Zachary has been a technical writer at GitHub and the Linux Foundation, and now works as a staff technical writer at Stripe. You can find all her online accounts at her website.
Interested in exploring approaches for collaboration and knowledge management on engineering teams? Why not try a tool developers already turn to regularly? Check out Stack Overflow for Teams, used by Microsoft, Bloomberg, and many others.
Tired of security bottlenecks? Today’s episode is sponsored by Snyk, a developer security platform that automatically scans your code, dependencies, containers, and cloud configs — finding and fixing vulnerabilities in real time, from the tools and workflows you already use. Create your free account at snyk.co/stackoverflow.
Tags: docs for devs, documentation, technical writing, the stack overflow podcast
5 Comments
Many great points in the podcast, though many points seem pretentious. It’s great to motivate people for documentation etc., but in many environments there isn’t the time. When you have the time, sure write it. Write great documentation. Write the best possible documentation and have you user in mind. Once you have that time though, why pretend as if you had this great and emotional insight why documentation matters? You were simply put into a situation where you had the time.
Have you tried “readme-driven development” where you start out writing documentation before you write code? In that setup you will have time to write documentation, and I find it really helps with project management since stakeholders can read your docs but they aren’t great at reading code or tests.
So, you kind of have to make the time if you aren’t granted it, but I think it’s worth it. If you have managers that get in your way, then maybe it’s not a great track, but good managers will want documentation, especially for staffing changes in this period of constant job hopping.
I came here expecting some real-world advice, but found nothing instead.
I need to write documentation. What tools should I use? Where should I start? How should I motivate the other developers (or members of the team) to write something?
I do agree with Felix’s points above 🙂
My advice is to use GiHub to host your repo, write in markdown, and publish with GitHub Pages. If you start writing stuff down that they start referencing frequently, hopefully, your team will see the use for writing and updating docs. I mean, they probably use a lot of documentation they didn’t write all the time so it shouldn’t be hard to get the point across. Motivation is another problem, but that’s far larger than just something about documentation.
The great thing about documentation is that a document should be seen as live documentation. You think you don’t have time, but start simple and work on keep adding (based on feedback, project requirements, good practices, etc), just write something that you’ll find useful, start looking at examples and create your own minimal template. With practice, you’ll have your mental model defined and things will get faster (i.e. you’ll find time)