Author(s): Terry Gichuhi, Roy Waswa and Abol Ger
Date: 03/08/2023
We all experience those incredible “Aha!” moments when everything falls into place. Whether it’s fixing a persistent bug or discovering a better approach to a problem, these bursts of enlightenment are like treasures we want to share with others. However, sharing knowledge isn’t always easy. While YouTubers like Brad Traversy make it look effortless, creating high-quality videos while breaking down complex topics on software development is not only difficult and expensive, documentation still remains one of the most effective way to communicate ideas and concepts to others within and without 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.
Reflecting on our own journeys, we cannot stress enough the significance of technical writing skills in a developer’s career. By mastering the art of technical writing, you unlock a powerful tool that amplifies your impact, opens doors to leadership positions, and ultimately paves the way for success in the dynamic world of software development.
One major benefit of developing your technical writing skills is the ability to communicate complex technical concepts clearly to different audiences, whether they are developers, project managers, or clients. This clear communication eliminates confusion, reduces errors, and ensures everyone is on the same page. Further, with a focus on syntax, error handling, and proper formatting, we have become more meticulous in our approach to documentation during development (and not waiting till the end) so that comments in the code also communicate better to others.
What is the end-game?
Having clear aims for your article 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 piece.
| 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?
Before you start writing, it’s crucial to identify your target audience. Whether it’s fellow developers, junior developers seeking guidance, or non-technical stakeholders, understanding your audience allows you to tailor your writing to their needs. Consider their preferences, what resonates with them, and relatable analogies. By envisioning a specific person who would appreciate your information the most, you can create a connection and give your writing a personal touch.
What is the message?
Create a detailed brief that outlines your main talking points and strengthens your content. Address common questions, share innovative ideas or solutions, and explain the methods you employed to reach those solutions. Your brief acts as a guide, helping you maintain coherence and flow throughout the writing process. It also allows you to work on your piece in parts.
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 tech 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.
The simple answer therefore is it depends. Here’s a brief summary, based on the authors’ collective experience, of the pros and cons of each platform that will guide you on selecting the appropriate 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
The aim of being able to write non-technically as a techie is to effectively communicate complex technical concepts and ideas to a broader audience. While technical expertise is essential in the field of technology, the ability to convey information in a clear, concise, and understandable manner to non-technical individuals is equally crucial. By honing their non-technical writing skills, techies can bridge the gap between technical jargon and everyday language, making their work more accessible and relevant to a wider range of stakeholders. This skill empowers techies to share their knowledge, ideas, and innovations with the public, decision-makers, and colleagues from different domains, fostering better collaboration and understanding across diverse fields. Ultimately, the aim is to democratize information, promote inclusivity, and enhance the impact of technology by making it more relatable and beneficial to all.
You can email noappforthis(at)openinstitute.africa to get in touch with the authors