The subtle art of writing software documentation

There’s an art to writing about software and making it seem easy to use, even to someone who may be completely unfamiliar with the product. Technical writing requires not just technical knowledge about the product you’re documenting, but also good communication and writing skills.

In this post, I’ll discuss how we approach the art of technical writing at Redpanda, and how our team strives to make our documentation better each day.

From test engineer to technical writer

Before I fell in love with technical writing, I was a test engineer for 10 years. I wrote DC parametric tests and functional tests, using a logic analyzer to simulate circuit behavior. I would read technical documentation written by people who didn’t understand the technology they were writing about, and this highlighted for me how important good documentation is.

I realized there was a huge need for people who were technical, but could also explain complex concepts clearly, organize information logically, and follow basic rules of grammar and composition. Since I’ve always enjoyed opportunities to share knowledge, the teaching aspect of technical writing really appealed to me. It’s rewarding to see the light bulb go off for someone when I explain a topic they previously didn’t understand.

To kick off my career change, I enrolled in the Technical Writing Certificate program at a local junior college. I also joined the Silicon Valley chapter of the Society for Technical Communication, so I could network with experienced writers.

Today, I document new features for each Redpanda release. I am mainly responsible for Redpanda Console documentation and all cloud documentation (which is coming soon!). I also recommend product improvements to our engineers and UI designers. A side benefit of making the product more user-friendly is that it is easier to document!

Why is software documentation important?

Good documentation helps users do their jobs well, reduces calls to Customer Support, and improves customer confidence in our product.

To me, the best documentation is well-organized, so you can easily find what you’re looking for — preferably without resorting to the search bar. Instructions are clear, complete, and easy to understand, so you can succeed at the task you’re trying to accomplish. The documentation anticipates your questions and answers them, so you don’t have to contact Customer Support for help. It also includes background information that helps you understand how something works, what the benefit of the feature is, or how one part fits into the bigger picture.

Writing documentation for a fast-growing startup

At a start-up, it’s common for people to wear many hats, so the company’s first documentation is often written by people who are not technical writers. Once technical writers are hired, we work on bringing consistency, structure, and polish to existing documentation. At the same time, we also work on documenting new features for each release.

The biggest challenge in this role is trying to catch up on documenting every feature and product that’s currently available in Redpanda. The company is growing quickly and constantly releasing new features, and we still have older features whose documentation we want to improve.

One of the advantages of working for a start-up is that we get to determine the tools, workflows, and processes that will improve our documentation and make our jobs easier. For example, our process for documenting new features starts with someone (usually an engineer or product manager) filing a documentation issue in GitHub. (Users can file issues for existing documentation here.) We then write the documentation in Markdown and submit a pull request in GitHub. Once key reviewers give their approval and the documentation goes through a round of editing, we merge the pull request to the appropriate branch. We then publish our documentation to Redpanda’s docs site using GitHub and Docusaurus. For existing features, we publish right away; for new features, we publish in tandem with the official announcement of the release.

How to become a technical writer at Redpanda

If you think you’d like to join Redpanda’s Docs team, my advice is to learn everything you can about streaming data platforms and Apache Kafka®. I’m fortunate that in my previous jobs, I learned about distributed systems and Kafka, so I was able to bring that knowledge to Redpanda. You should also have relevant technical writing samples that show off your writing ability, and brush up on your Git skills. Empathy is another important skill, since we are customer-focused user advocates.

Documentation is a fairly small team right now, but we’re looking to grow! If you’re interested in joining me in Documentation, or you’re interested in another role at Redpanda, check out our careers page to see our open positions.

Join the Redpanda Community on Slack to post your Redpanda and industry-related questions, and send us your docs feedback at rp-docs-feedback@redpanda.com. (Seriously! Tell us what you think. We love hearing from our users!)

‍