While good documentation is key to good applications, the definition of ‘good’ continues to evolve. Rather than the dry technical documents of the past, today’s documentation is a lot like any other type of content. It must be engaging, accessible, and targeted to its audience; in fact, it may not even be a written document, but a video, podcast, or even a social media feed.
As a documentation engineer at Meta, Brittney Ball focuses on crafting documentation that helps the company's current and future engineers use Meta’s many products and platforms. In our most recent episode of Decoded, Brittney chatted with host Sydney Lai to share her journey to documentation and why documentation is key to creating an inclusive culture.
Using documentation to Build a Career
Ball didn’t follow a traditional path to tech. Several years back, she was a single mother living in a shelter and knew she needed to find a career that didn’t require a college degree. By teaching herself how to code, she learned the skills required to get her foot in the door and launch her career.
In addition to online courses, Ball found herself learning from developers who posted tutorials on YouTube or who would answer her questions on Twitter. While there are near-limitless resources for learning, Ball quickly learned that not all content is accessible and inclusive to all types of learners.
As a documentation engineer, she sees her job as an opportunity to teach new skills in a way that is accessible for all. As Ball explained:
“It’s been a passion for me to help others who experience the same journey as I did breaking into tech. I want to make sure my documentation is inclusive of everyone and that they don't have the same struggles I did.”
By making documentation accessible, Ball also believes it can be a competitive advantage for retaining employees:
“If you’re working in a company and can’t understand your job via documentation, tutorials, and guides, you’re going to want to go somewhere else. If you want a great retention rate, it starts there.”
Writing Documentation That’s Relatable for Developers
Thanks to her experience, Ball brings an approach to documentation that is designed to feel more human and that meets the developer where they are. She notes that more and more newer engineers are self-taught compared to previous generations, and that younger learners have more ways they like to learn than just reading a long technical doc. Not only that, she is sensitive to the fact that the words she uses can have a major difference in how the documentation — and the learning — is conveyed. She said:
“When I’m writing, I’m really aware that people have different learning styles, so I try to incorporate all of the different forms of learning. I incorporate videos, but try to keep them short because not everyone has the same kind of focus. When I do documentation, I make sure to break down everything. I don't use technical jargon or words that will trigger imposter syndrome. I want to make everyone feel like they deserve to be here.”
In a company like Meta, documentation is a massive, ongoing undertaking. Different documentation engineers focus on specific aspects of the company’s products so that they can become as well-versed as the developer. Not only that, but they must continuously audit documentation to ensure it reflects the current product. Ball said:
“Because technology is ever-changing, oftentimes documentation is no longer correct or relevant. And because Meta is such a huge company, there are a lot of documents, so we are always auditing, correcting, and updating.”
The Future of Documentation
Ball believes that documentation engineering will continue to evolve to meet not only audience expectations, but the growing communication skills of engineers. It’s no longer uncommon to see technical people documenting their projects on blogs, YouTube, Twitch streams, Twitter feeds, or any number of channels.
“These are the people who should be applying for documentation engineering jobs, because they break it down and make it interesting and fun. Super-duper technical writing is boring. You have to put some personality in it. I think this new generation is going to take documentation engineering to the next level because they have a passion for it; it’s so different to how it was taught 20 years ago.”
For Ball, the secret to success is something you might not associate with a how-to manual: empathy. This allows the writer to put themselves in the shoes of the reader so the content they create is more approachable, and ultimately more useful.
“At the beginning of my career, I didn’t feel like I belonged because I was reading technical documentation that had all these big words or code examples that weren't interactive. Great documentation makes people feel like they can do this. We have to do better to make sure everyone feels included.”
Catch the full episode to hear more about Brittney’s insights and expertise in documentation. And be sure to subscribe to the Decoded podcast.