Open-source development is often seen as a cycle of writing code, pushing commits, and fixing issues. But beneath every well-crafted project lies something even more valuable: the thought process behind it.
When I started working on Waveu, I realized that putting ideas into words was just as crucial as writing the code itself. Documenting its inspiration, defining class interfaces, and visualizing waveform generation not only helped me refine my ideas but also made the project more approachable for others.
Yet, in the open-source world, writing technical notes isn’t a common practice. Many developers assume that code speaks for itself. But does it really?
In this article, I’ll share why writing technical notes is an underrated yet powerful tool for open-source projects and how it shaped the development of Waveu.
1. The Thought Behind Waveu #
Waveu didn’t start with code—it started with questions:
- What if waveform generation was more flexible on microcontrollers?
- How can we balance performance with ease of use?
- How do we ensure adaptability across different hardware environments?
These ideas weren’t something I could “just code out” immediately. Writing them down helped refine the scope and direction of the project before a single line of code was written.
Why Write It Down? #
Writing technical notes before jumping into code forces you to clarify the why behind your decisions. Even if no one else reads them, your future self will thank you.
2. Putting Ideas Into Words #
Turning an idea into an open-source project isn’t just about writing code—it’s about defining the core concepts, designing interfaces, and making the project understandable.
When working on Waveu, I documented my thought process in three key areas:
🌀 Inspiring Ideas – Every project starts with a spark. I explored how waveform generation could be made more accessible on microcontrollers, balancing flexibility, performance, and usability.
📏 Class Interfaces – Before writing implementation details, I defined clear interfaces that would structure the project. Writing about how components should interact helped ensure extensibility.
📊 Visualizing Waveform Generation – Waveform output isn’t just numbers; it’s something that can be seen on an oscilloscope. Documenting the visualization process helped shape the API design for user interactions, such as starting and stopping waveform generation.
By documenting these ideas in a concept note, I could refine Waveu’s direction before committing to an implementation. This approach helped avoid unnecessary rewrites and kept the project focused.
👉 Read the full concept note on Figshare
From Inspiration to Implementation #
- Writing about ideas, interfaces, and visualization helps shape a project before coding.
- Well-defined class structures make a library easier to extend.
- The best technical notes don’t just describe what a project does—they explain why it was designed that way.
3. Building Reference Implementations #
Code examples aren’t just there to show usage—they should reinforce why the design works the way it does.
Waveu’s Reference Examples:
1️⃣ PhaseGenerator-only sawtooth wave → Shows basic DDS functionality.
2️⃣ LUT-based triangular wave → Demonstrates index calculation and symmetry.
3️⃣ Dual-channel waveform example → Highlights real-world complexity and synchronization.
Each of these examples is available in the Waveu GitHub repository as a working implementation. Writing these examples not only helped clarify the API but also served as a test of Waveu’s design decisions.
More Than Just Demos #
Instead of only writing code, build examples that:
- Validate design choices.
- Serve as self-documenting features.
- Show not just how to use your library but why it works.
Conclusion #
Code isn’t just syntax—it’s an expression of ideas. If those ideas are never written down, they get lost in commits, buried in PRs, or forgotten over time.
Writing technical notes helps:
✅ You – By clarifying ideas before implementation.
✅ Your future self – When revisiting a project months later.
✅ Contributors – Who need context beyond the code.
✅ The community – By sharing insights that others can build on.
Open Source Needs More Technical Notes #
💡 Challenge: The next time you start an open-source project, try writing down why you’re building it before touching code. You might be surprised at how much clearer your thinking becomes.