FOSS Backstage 2025

Beyond Words: Crafting User-Friendly Documentation
2025-03-11 , Wintergarten

Good documentation is essential for open source, yet often overlooked. In this workshop, you will learn simple, hands-on techniques to create documentation that is clear, engaging, and user-focused.

Walk away with a draft piece and a personalized toolkit for improving your docs and boosting your project’s accessibility.


Imagine a developer new to an open-source project, full of enthusiasm but frustrated by documentation that is dense, confusing, or incomplete. Without reliable guides, they might struggle to contribute or even lose interest in using the software. Many open-source projects face this challenge, as documentation often fails to resonate with users.

In this hands-on workshop, we will dive into practical techniques that make technical documentation clear, accessible, and highly usable.

Participants will:
1. Learn to structure content for usability, making information logical and user-centered.

  1. Simplify complex technical details with clear, concise language.

  2. Incorporate visuals like flowcharts, diagrams, or screenshots to make documentation more accessible.

  3. Design simple feedback loops to keep documentation relevant and up-to-date.

We will cover:

Introduction:
a. Explain the importance of good documentation in open-source projects.
b. Walk through what the workshop will cover.
c. Show examples of bad vs. good documentation to set the stage.

Topic 1: Structuring Documentation for Clarity:
a. Teach participants how to organize content in a way users can easily follow.
b. Use slides to show examples of clear outlines and logical flow.
c. Simple Exercise: Create or improve an outline for documentation.

Topic 2: Writing in Simple Language:
a. Explain how to remove jargon and write in a user-friendly way.
b. Use slides to share "before and after" examples of simplified text.
c. Simple Exercise: Rewrite a short technical paragraph to make it easier to read.

Topic 3: Using Visuals Effectively:
a. Show how visuals like diagrams, flowcharts, or screenshots make complex ideas clearer.
b. Demonstrate tools for creating visuals quickly.
c. Simple Exercise: Pick a part of your documentation and sketch a visual aid for it.

Feedback and Iterative Improvements:
a. Explain how to gather feedback from users and improve documentation over time.
b. Create a checklist for ongoing improvements.

Live Critique and Wrap-Up:
a. Participants share their draft outlines or rewritten text for group feedback.
b. Highlight the key takeaways and distribute the "sticky documentation" checklist.

Why It Fits FOSS Backstage
This workshop supports open-source growth and inclusion by giving participants the skills to create documentation that welcomes users and contributors from diverse backgrounds. It’s simple, actionable, and designed for anyone involved in open source.

Zainab Daodu is a seasoned Senior Technical Writer with over 6 years of experience across technical writing, software engineering, and DevOps. At her current position, she is driven by a mission to make complex technology accessible through clear, impactful documentation.

Starting her career as a software engineer at Interswitch Group, Zainab discovered a passion for enhancing developer experiences, and her expertise has since contributed to global platforms like Google, Cisco, Tealium, and open-source projects like Jenkins and the Wikimedia Foundation.

As the founder of WriteTech Hub, Zainab formalized her commitment to mentorship and community growth, training over seventy (70) technical writers some of whom now work in top tech companies. She has also led diversity initiatives with She Code Africa, impacting over five hundred (500) African women in tech through programs like Women of Open Source Community Africa (WOSCA) and Contributhon.

Through her work and insights, Zainab continues to shape the future of technical writing and promote diversity in open-source communities.