With over 30 years of working in UX design (since 512 x 342, for those in the know) and, more recently, working on open-source software, I continue to see a common challenge in how projects evolve: maintaining focus on the problems we're solving rather than jumping to features - even my own projects need this discipline. Without maintaining focus on the problems we're solving and for whom, both the project and our documentation can end up reflecting that same lack of clarity.
There's a better approach.
While developing Docsify-This, an open publishing tool, I created a three-section framework that evolved to serve a dual purpose:
Here's how it works and why it might help your project too.
The Docsify-This examples shown here aren't the result of applying this framework - they're what led me to create it (a.k.a. live the story, tell the story). I extracted these patterns from my documentation work, and continue to evolve both.
Start with the problem and solution in 1-2 concise sentences:
<aside> <img src="/icons/light-bulb_gray.svg" alt="/icons/light-bulb_gray.svg" width="40px" />
Specificity Beats Generality
Compare these: ❌ "Makes publishing easier and faster" ✅ "No web server, website setup, or build process required"
Users recognize their own needs in concrete details, not vague promises.
</aside>
Example from Docsify-This:
Docsify-This provides a quick way to transform and style Markdown content into visually appealing web pages without requiring a web server, website setup, build process, or in-depth technical knowledge. Designed to support OER and open publishing workflows, it enables almost instant publishing and seamless content distribution across multiple platforms.
Then follow with: "With [Project] you can..."