Docs for Developers: An Engineer’s Field Guide to Technical Writing

By Jared Bhatti, Sarah Corleissen, Jen Lambourne and 2 more

Learn to integrate programming with good documentation. This book teaches you the craft of documentation for each step in the software development lifecycle, from understanding your users’ needs to publishing, measuring, and maintaining useful developer documentation.

Well-documented projects save time for both developers on the project and users of the software. Projects without adequate documentation suffer from poor developer productivity, project scalability, user adoption, and accessibility. In short: bad documentation kills projects. 

Docs for Developers demystifies the process of creating great developer documentation, following a team of software developers as they work to launch a new product. At each step along the way, you learn through examples, templates, and principles how to create, measure, and maintain documentation—tools you can adapt to the needs of your own organization.

What You'll Learn

• Create friction logs and perform user research to understand your users’ frustrations
• Research, draft, and write different kinds of documentation, including READMEs, API documentation, tutorials, conceptual content, and release notes
• Publish and maintain documentation alongside regular code releases
• Measure the success of the content you create through analytics and user feedback
• Organize larger sets of documentation to help users find the right information at the right time

Who This Book Is For 

Ideal for software developers who need to create documentation alongside code, or for technical writers, developer advocates, product managers, and other technical roles that create and contribute to documentation for their products and services.

 

• Language: English
• Publisher: Apress
• Release date: Sep 30, 2021
• ISBN: 9781484272176

Book preview

© The Author(s), under exclusive license to APress Media, LLC, part of Springer Nature 2021

J. Bhatti et al.Docs for Developershttps://doi.org/10.1007/978-1-4842-7217-6_1

1. Understanding your audience

Jared Bhatti¹  , Zachary Sarah Corleissen², Jen Lambourne³, David Nunez⁴ and Heidi Waterhouse⁵

(1)

Berkeley, CA, USA

(2)

Victoria, BC, Canada

(3)

Cornwall, UK

(4)

San Francisco, CA, USA

(5)

Mounds View, MN, USA

Corg.ly: One month to launch

Charlotte was frustrated. The launch date for Corg.ly was just a few weeks away, yet it took the entire engineering team (well, all five engineers) an afternoon to get a single user started.

../images/505277_1_En_1_Chapter/505277_1_En_1_Figa_HTML.jpg

Mei, their alpha customer, was extraordinarily patient as Charlotte demonstrated how Corg.ly worked and how to use the API. Charlotte had spent the previous hour sketching out a system diagram, some of the design decisions made, and how endpoints sent and received data. Ein, the company dog and official product tester, had happily demonstrated how bark translations worked in exchange for a few dog biscuits.

Reflecting on the time spent in this meeting, Charlotte realized these sessions were time consuming and costly. If the product was going to scale to the large audience they projected, users were going to have to get started by themselves, and quickly.

As if reading Charlotte’s mind, Mei leaned back in her chair. I still have a lot of problems getting this working, and I know I’ll have a million more questions once I do. Can you send me the docs when they’re ready, and I’ll happily give it another try?

Of course, Charlotte said. She felt a pit open in her stomach as a montage of vignettes from the past six months flashed through her mind: multiple instances where she had said things like, Let’s wait on the documentation, since everything is just going to change anyway... Let’s deprioritize the documentation for now, since there’s so much else to do... We probably don’t need to worry about documentation right now since the code is self-explanatory...

Thanks, said Mei. I’m excited to share this with the rest of my team, but I know you’re the experts. It’s going to take time to teach the developers on my team how to develop against your API, but we need to start soon. We’re hoping to produce several million dog translator collars for Christmas this year.

Sure thing. We’ll polish up the docs and share them when they’re ready. We should have drafts ready in the next few weeks, responded Charlotte.

As the lead engineer, she architected the product and worked closely with her coworker, Karthik, to dole out the tasks and assignments to everyone, none of which included documentation. Corg.ly was in fact heavily documented—in a mishmash of emails, scattered meeting notes, and pictures of whiteboards. As the architect of the product, she had an intimate knowledge of the code, what it could do, and the trade-offs they made along the way.

Corg.ly is so easy for me to use, I didn’t think about how hard it might be for others, Charlotte thought to herself after the meeting. Where do I start?

The curse of knowledge

In the late 1980s, a group of economists at Harvard determined that humans assume others have the same knowledge they do. They named this cognitive bias the curse of knowledge.¹ A few years later, a Stanford PhD student demonstrated the curse in an experiment. She asked one group of participants to tap their fingers to the rhythm of a well-known song while another group of participants listened to the taps and tried to guess the tunes. The tappers, with the song fresh in their mind, assumed their listeners would be able to guess the majority of songs.

Listeners didn’t.² Tappers guessed that listeners would predict the song 51% of the time, but the unfortunate listeners only got the song right a mere 2.5% of the time.

It’s likely you’ve been on the receiving end of the curse of knowledge. A coworker may have used jargon you weren’t familiar with, forgot to mention an API endpoint they assumed you would find, or pointed you to an error message with very little information on how to fix the problem. For Corg.ly, Charlotte has spent so much time with the product that she knows it perfectly, but the first few users trying out the product have no idea how to make sense of it.

Breaking the curse, and writing effective documentation, requires empathy for your users. You have to understand what your users want from your software, and where they need help along the way. Through user research, you can understand your users’ needs well enough to predict what they need before they need it. By performing user research before you put pen to paper or hands to keyboard, you’ll set your users on the path to success.

This chapter guides you through breaking the curse of knowledge and understanding your users by:

Identifying the goals you have for your users

Understanding who your users are

Understanding your users’ needs and how documentation addresses them

Condensing your findings into personas, stories, and maps

Testing your assumptions with a friction log

Creating an initial sketch of your users

To write effectively for users, you need to understand who they are and what they want to achieve.

Start by gathering and reviewing any existing materials you already have about your product or your users. These could include old emails, design documents, chat conversations, code comments, and commit messages. Reviewing these artifacts will help you build a clearer picture of how your software works and what you intend your users to do with it.

Users also have their own goals that may or may not match those of your organization. An initial review can help identify any initial gaps or mismatches between these different sets of goals.

Defining your users’ goals

Once you review your existing knowledge, the next step is to understand what your users want to accomplish from reading your documentation. Knowing your users’ goals will guide your research and focus your efforts on documenting the most relevant information.

Consider: why are you writing this documentation in the first place? You don’t just want your users to know something about your software; you want them to complete a set of tasks or change their behavior in some way. There is an engineering goal (for them) and a business goal (for you) that you want your users to reach.

At Corg.ly, Charlotte needs to onboard as many new users to Corg.ly as possible for the business to be a success. The goal of Corg.ly documentation can be summarized as

Onboard new users to Corg.ly by helping them integrate with Corg.ly’s API.

By contrast, the most common goal of Corg.ly users is

Translate my dog’s barks into human speech.

The goals of Corg.ly and Corg.ly users are different, but they can still align in a single documentation set. You probably have a goal for your users as well. Identifying how different goals can both differ and overlap helps you gain empathy and meet needs