Have you ever had those breathtaking “Aha!” moments when everything suddenly clicks into place? It could be solving a stubborn bug or stumbling upon a brilliant solution to a problem. These flashes of insight feel like precious gems that we eagerly wish to share with others. Yet, the act of sharing knowledge is not always a simple task. While YouTubers like Brad Traversy make it seem effortless, producing top-notch videos that demystify complex software development topics is not only challenging but also costly. That’s why technical writing continues to be one of the most effective means of conveying ideas and concepts, both within and beyond the tech community.
Why Technical Writing Skills Matter
As a developer, the ability to articulate your ideas, share knowledge effectively, and foster collaboration through well-crafted technical documentation is invaluable. It enables you to seamlessly onboard new team members, bridge gaps between technical and non-technical stakeholders, and empower users to utilize your software solution effectively.
Over the past 9 months, the authors of this blog post have interacted with medical practitioners, policy makers, technology enthusiasts, patients and caregivers, who comprise the non-technical stakeholders that are too often overlooked when developing documentation for technical projects.
What are some of the informational needs that different stakeholders might have?
Medical Practitioners: Building digital health applications requires attention to detail, and this extends to the technical writing. For medical practitioners seeking to understand the process behind health app creation, consider that precise technical documentation is what bridges the gap between technology and healthcare. It ensures that the apps are not only functional (that is, fit for use and purpose because lives are at stake) but also safe and effective for patient care. By delving into the documentation, medical practitioners gain insights into how the app operates, overcoming trust issues and eventually leading to improving patient outcomes.
Policymakers: Technical writing plays a significant role in regulatory compliance. Policymakers hold a significant role in shaping the digital health landscape, and must grasp the importance of clear technical documentation. It enables policymakers to define and enforce rules and standards that safeguard patient data, ensure app safety, and promote interoperability among different health systems. By advocating for robust technical documentation standards, policymakers can foster a transparent and accountable environment for digital health innovation. In doing so, they support the development and deployment of apps that meet the highest quality and safety standards, benefitting both healthcare providers and patients.Technology
Enthusiasts: Tech enthusiasts, on the other hand, should understand that technical writing is important in the innovation process including documenting progress. It fosters collaboration among developers, medical professionals, and policymakers. Documentation also serves as a historical record of technological advancements, enabling enthusiasts to track the evolution of health tech and contribute to its growth.
What is the end-game?
Having clear aims for your technical documentation serves as a compass to keep you on track. Whether you want to provide information, guide readers, or explain complex concepts, outlining your aims helps you filter your thoughts and focus on what’s relevant. It ensures a cohesive and purposeful article.
In healthcare technology, precision and transparency are paramount, given the sensitive data and ethical responsibilities involved. Clearly defining your objectives in your technical documentation is not just good practice; it is a moral obligation. In healthcare, this takes on profound significance, where full disclosure and unambiguous objectives are essential principles.
For example, in this post, we’re aiming to provide you with practical tips and guidance to help you, developers, improve your technical writing skills such as identifying the audience, creating a detailed brief, structuring your content while maintaining clarity and simplicity, and being deliberate about the online platforms where to publish. We keep in line with this by posting the article on Medium as well.
Who am I targeting?
As stated above, before you start writing, it’s crucial to identify your target audience; understanding your audience allows you to tailor your writing to their needs. Consider their preferences, what resonates with them, and relatable analogies.
Just to expound on the needs and objectives of the non-technical stakeholders mentioned earlier; medical practitioners see technical documentation as a bridge between the complex technology that powers these apps and the medical expertise required to utilize them effectively. By delving into the documentation, they gain insights into the app’s functionalities, data security measures, and potential limitations. Patient safety and data privacy are paramount, therefore well-documented apps with robust security measures become a trusted part of their healthcare arsenal. The role of policymakers in the digital health landscape is pivotal for safeguarding the health and privacy of citizens. Technical documentation plays a crucial role in regulatory compliance and oversight, serving as a source of standards for transparency and accountability.
A regulatory sandbox for example is a tool that enables policy makers understand the benefits and risks of health apps in the real world – before they introduce regulations. Consequently, documentation generated in this process both accelerates innovation while maintaining safety.
Imagine a world where tech enthusiasts collaborate with developers to develop documentation, allowing for diverse perspectives and expertise to shape both the narrative as well as the designs.
What is the message?
Create a detailed brief that acts as a guide, helping you maintain coherence and flow throughout the writing process.
The content of your piece should also flow from the audience you’re targeting and their level of experience. When addressing those with limited experience, break down complex concepts into simple principles. But it is okay when writing for peers to utilize technical jargon – as long as your goal is to communicate concepts and ideas. Altogether, striking the right balance between accessibility and technical depth will ensure your content resonates with and adds value to your readers.
Below are additional tips that you can incorporate when writing your article.
- Clarity and Simplicity: In technical writing, clarity is paramount. Avoid convoluted sentences and ambiguous language. Be concise and get straight to the point. Use clear explanations, examples, code snippets and visuals when necessary to enhance understanding.
- Structured Approach: Organize your article with a logical flow. Use headings, subheadings, and bullet points to break down complex topics into digestible chunks. This makes it easier for readers to follow your ideas and locate specific information.
- Bridging Theory and Practice: As developers, we often deal with abstract concepts that can be challenging to grasp. Whenever possible, provide real-world examples and practical applications to help readers connect theory with practice.
Once your piece is ready, it’s time to consider where to publish it. Choose a platform that aligns with the target community’s interests and preferences. Even on a more generic platform like Medium, Github or Stack Overflow, targeting a specific tech-oriented community can greatly increase the appreciation and engagement with your piece.
So where should one publish? Here’s a brief summary, based on the authors’ collective experience, of the pros and cons of each platform:
| Platform | Pros | Cons |
| Medium | Wide audience and visibility; Easy to publish and share | Less focused on technical content |
| Github | Developer-centric; Widely used for code sharing | Limited visibility outside the developer community |
| Stack Overflow | Accessible community of experts; Focused on Q&A and problem-solving | May require more experience to contribute meaningful content |
These are not the only platforms; tools (like Kaggle), discussion boards, forums exist which can be leveraged based on the message and the type of community being targeted. Of importance is to remember to think about the cost/benefits of the platform chosen.
Cross posting could also be an option; this occurs when an author shares the same post or content on multiple social media platforms or online forums. Typically, they would publish the same message, image, video, or link on different platforms simultaneously. This allows the user to reach a wider audience and ensure that their content is visible to all of their followers or community members, regardless of which platform they prefer to use. Cross-posting can increase the visibility and engagement of their content and maintain a consistent online presence across various platforms. However, it is essential to be mindful of the context and audience on each platform to ensure that the content remains relevant and tailored to the specific platform’s users.
Conclusion
Technical documentation is the backbone of successful software development. As developers in the field of digital health applications, you are at the forefront of delivering innovative solutions that can impact lives positively. However, the success of your work relies heavily on the quality of your technical documentation. Detailed and well-structured technical documentation not only helps you and your team understand the intricacies of the software but also facilitates efficient collaboration. It serves as a reference guide, enabling smoother troubleshooting, debugging, and maintenance. Moreover, in the context of health apps, accurate documentation is paramount for ensuring patient safety and regulatory compliance. By investing time and effort in creating high-quality technical documentation, you not only enhance the usability and reliability of your apps but also contribute to the overall advancement of healthcare technology. This makes your work more accessible and valuable to the team and the end-users.
This post was written by designers currently taking part in a project called NoAppForThis, an action research project by Wellcome Trust, implemented across 3 countries (Kenya, Uganda, and South Africa) by the Open Institute, CIPESA, and CEHURD, working in collaboration with the of University of Warwick in the UK, University of Nairobi, and University of Witwatersrand in South Africa.
You can email noappforthis(at)openinstitute.africa to get in touch with the authors. Terry Gichuhi, Roy Waswa and Abol Ger.
