In Part 1 of this blog series, we discussed the developer-focused “docs as code” system to simultaneously facilitate and enhance contributions and grow a user base throughout the dev cycle. We also heard from VMware’s Staff Technical Writer Alyssa Rock and her steering committee affiliation with The Good Docs Project, a valuable resource that provides best practice templates and writing instructions for documenting open source software.
In this blog, we’ll discuss four types of documentation, and how new contributors can get their hands dirty improving docs by creating friction logs, reviewing templates for errors and making beginner-friendly contributions in GitHub, all intended for building better documentation practices for developers.
Doc Types and the Solutions They Provide
What if you have a stellar project but it lacks good documentation — are you hearing crickets? That’s because without up-to-date, detailed and reliable documentation to effectively guide developers on its use, they’ll disregard your project and look for another one that fits their needs.
So keep ‘em around with good docs!
There are many types of documentation but in this blog, we’ll focus on four of them—tutorials, how-to guides, explanation and reference—with the understanding that each doc is structured according to serving a distinct purpose. Why the distinction? Because developers require different information at different stages of development and it’s essential that comprehensive documentation be on hand throughout the entire dev cycle.
Let’s briefly review each type of doc and its part in attracting users and providing effective guidance to the utility of the project.
- Tutorials (skills-based) explain how the project technology works or why the technology matters for solving a user’s issue. They demonstrate use case A and B, and depict the best scenario. Docs Advocacy Expert Erin McKean of Google and The Good Docs Project puts it this way: “If a user finds the project’s code useful, the tutorial will help them build a mental model to conceptualize everything the project can do.” Think of tutorials as an upsell doc, she says.
- How-to Guides (solutions-based) provide users who already have some understanding of basic tools through the steps to arrive at a specific solution. How-to’s are written in such a way that assume the user knows what they’re meant to achieve, but doesn’t know which action to take. The difference between a how-to and a tutorial? The former solves the problem users have and the latter solves the problem you want them to have. If your project isn’t attracting a healthy number of users, creating a How-to Guide will help them onboard with clear instructions on getting started.
- Reference Guides (facts-based) contain technical descriptions of the project’s technology and how to use it. They’re code-determined and describe APIs, sample config files, glossaries, error codes, prerequisites, and include external links to further reading. Reference Guides differ from How-to Guides in that they describe correct usage of the software as opposed to showing how to use it to achieve a certain solution. Erin McKean says, “reference docs are the helping hand over rough ground and give your user confidence to move forward and use your tool, project or code.”
- Explanation Guides (knowledge-based) illustrate concepts (e.g. technical blogs, videos, zines!) that clarify your project around deployment, security and accessibility. Think of the information in explanation guides as discussion from a different perspective. Software Developer Julie Evans approaches Explanation Guides with the Wizard Zines she creates, which focus on fundamentals (e.g. “Bite-size Command Line,” “Linux Debugging Tools You’ll Love,” “Profiling and Tracing with PERF”) and show how topics traditionally considered “hard” and “scary” are actually accessible and interesting and fun.
Concerning the content of Explanation Guides, Erin says, “pour your enthusiasm into text and break down the barriers to understanding your tech or why the tech matters.”
The aforementioned types of documentation are good fodder for the new contributor to get their hands dirty, making improvements for readability (correcting typos, grammar) and updating content. We’ll get into how you can look for projects to do just that, but first, let’s talk about creating friction logs, one of the easiest and most valuable ways to start making a meaningful contribution to a project right away (by the way, new hires make great friction loggers!).
Getting Stuck Is Worth Calling Out
Consistent APIs, logical defaults, straightforward “getting started instructions” and uncluttered UI are the things that make good projects. Enter friction logs. Friction logs are a play-by-play account of a user’s experience with a new tool. They’re incredibly helpful because new users don’t yet have “the curse of knowledge” that prevents seasoned contributors from seeing the hiccups in the experience of using that tool for the first time.
When you’re new and you feel like you’re having an impact on docs and the development process of sample apps, it’s a big deal.
–Suz Hinton, Software Developer at Stripe
New users can create friction logs as they onboard with new tools by listing out the steps taken to use the software and noting what went well and what didn’t. Or as the book Docs for Developers explains, “record your experiences, log each step sequentially, noting the behavior you expect and the actual behavior of your software. The bigger the gap between expectations and reality, the bigger the opportunity to improve your docs or software.”
In simpler terms, step through a use case, assign a rating (a one-word descriptor) and note whether you feel ease (“delight”) or unease (friction).
When the task is completed, the user can open an issue, attach the friction log, and send it to the open source maintainers. Think of creating friction logs as Google’s Erin McKean does: “it’s like taking your experiences and wrapping them up like a gift, then sending it along to someone who will cherish that gift of knowledge very, very much.”
Wondering what a friction log looks like?
Fig: Example Use Case Friction Log
Note that the shape and form of indicators describing the flow of an experience can vary. Some developer product sites assess feedback with a stoplight-colored indicator in the log — green, yellow, red — where Green is “delight,” yellow is “frustrating,” and red is a “full stop.” And note, “Blocker” and “Red” are especially crucial feedback, for it indicates a user got so hung up in the process that they had to begin all over again. Had it been an authentic end user, they may have bailed out of the app altogether in frustration.
Friction logs are a great way to start making valuable contributions!
Join the Write the Docs Community
If you’re gung-ho to improve docs beyond friction logs, join Write the Docs on Slack to get involved with the community and take a look at their website which has a wealth of learning resources. And it’s not too late to join 600 other folks in exploring the art and science of documentation at the Write the Docs Portland 2022 Virtual Conference, May 22-24.
Become a “Templateer”
Why not focus on reducing friction in templates and raise an issue in the templates repo in The Good Docs Project on GitHub? Or join one of the Project’s working groups, which consist of two or more “templateers,” collaborating together to work on a Good Docs Project initiative or focus area. The working group home page lists nine different groups, with a detailed description of each one’s objective, and includes a point of contact, meeting notes and current members. Working groups are open for anyone to join as a general rule and are organized on a temporary, ad-hoc basis or long-term, permanent basis if there is sufficient interest to maintain them.
And the best thing?
Contributors can belong to as many working groups as they have time for and it’s okay to join a group to observe for a while before contributing. Questions? Not sure where you’d like to get involved? Join The Good Docs Project Slack channel and ask away.
Contribute in GitHub
It’s easy to sign up for a GitHub account and begin making beginner-friendly contributions (step-by-step instructions are provided by scrolling down on the page). If you’d like to suggest a change in one of the tutorials or the workflow, raise an issue and embark on a discussion to better understand the problem, get more people involved and make a collective decision. You can also learn best practices for making a good first issue in Diana Atanasova’s recent blog, A Beginner’s Guide for Contributing to an Open Source Project…Code and Non-Code Contributors Alike! (Part 1).
If you want to learn more about the technical details in creating your first PR and a fork, git commands and GitHub, read Anna Jung’s blog post 5 Things You Should Know Before Getting Into Open Source.
You Have the Power to Empower Developers
Docs advocacy is dev advocacy. Study the learning resources on Write the Docs and determine an area where you’d like to contribute. Join the community, say hello and make your initial contributions. Before you know it, you’ll be progressing quickly, gaining confidence and ability and adding more value. For every step you take towards making documentation practices better, you not only empower developers who hold the key to change, but positively affect the culture and communities around you.
So go ahead, as the folks at Write the Docs like to put it, and become a “documentarian,” and make your mark in the world as someone who cares about documentation!
Thanks again to Alyssa Rock for her valuable input to this blog, whose enthusiasm and love of docs is contagious.
Stay tuned to the Open Source Blog and follow us on Twitter for more deep dives into the world of open source contributing.
Resources to Make Docs Easier for Developers
- Google’s free course on technical writing designed to be run by communities of learners.
- The Season of Docs which provides support for open source projects to improve their docs and gives professional tech writers an opportunity to gain experience in open source and github.com/google/opendocs, a repo that contains useful templates for creating software documentation, created by the Cloud iX team at Google.
- Docsy when you’re good and ready to set up a documentation website.
