Writing data documentation is more than just outlining technical details; it’s about creating a bridge between developers, engineers, and users. Early in my career, I thought documentation was simply about writing clear instructions. But after working with large-scale data platforms at places like Expanso and Redpanda, I realized it’s far more involved.
The process goes beyond describing how a system works. It’s about ensuring the users—whether they’re engineers or non-technical stakeholders—can interact with the data efficiently.
The first step in creating useful documentation is truly understanding the product. It’s crucial to collaborate with engineers, ask questions, and even run queries yourself. At Expanso, for example, the high-performance data streaming platform we worked on was complex, and documenting it accurately required me to get familiar with every aspect of the system. Without understanding the system fully, it’s impossible to write documentation that is both useful and accurate.
Once I’ve grasped the system, the next challenge is breaking down complex information into digestible pieces. While working on a sophisticated data integration tool, I had to make sure that the documentation would be accessible to a wide range of users, from beginners to experts. It’s tempting to overcomplicate things because the system is complex, but I’ve learned that simplicity is key. Clear, easy-to-understand documentation ensures that users can grasp how the system works without feeling overwhelmed.
As the draft comes together, it’s important to keep testing and updating the documentation. The tech world moves fast, and the documentation needs to keep up. Documentation is never truly finished; it needs to evolve as the product evolves.
Review and feedback from real users are another critical step. Working with engineers is important, but getting feedback from actual users—people who will be using the system—is just as essential. This helped us pinpoint areas where the documentation was unclear or too technical, allowing us to make improvements.
When the documentation is finalized, delivering it effectively is the next hurdle. I’ve found that integrating documentation directly into the product interface can make it much more accessible. Some users prefer traditional written guides, but others may need interactive tutorials or videos. At Expanso, we worked on delivering the documentation in ways that would suit various user preferences, making the content as useful as possible.
Even after delivery, the process isn’t over. Feedback and updates often come in after users start interacting with the product. Sometimes it’s as simple as refining a sentence, but at other times, it might mean revisiting a whole section to reflect new features. Continuous improvement is key to keeping the documentation relevant.
Writing data documentation is an ongoing process of understanding, creating, testing, delivering, and refining. Over the years, I’ve come to appreciate how this process shapes the user experience. It’s not just about documenting a system—it’s about building a relationship between the product and the user, ensuring clarity and trust every step of the way.
Content Credit:
Sooter Saalu is a data professional and technical writer specializing in documentation for data and DevOps products. As a documentation specialist at Draft.dev, he consults on technical articles and has contributed to over 100 pieces for clients like Redpanda and Dataiku. With a background in psychology and computer science, Sooter effectively communicates complex concepts to diverse audiences and has also worked on open-source projects such as Bokeh and Bacalhau.
