One of the easiest traps to fall into as a library author is believing that examples are enough.
They’re not.
Examples prove that a feature works.
Real projects prove that a library works.
Those are very different things.
Over the last few months, I’ve spent a lot of time thinking about frameworks, APIs, design systems, and developer tooling. Like many developers, I’ve built countless demo applications to test ideas.
A sample website.
A sample API.
A sample component.
A sample workflow.
Everything looked great.
Until I started building real applications.
That’s when the interesting lessons began.
Demo Projects Are Controlled Environments
Most examples are designed to succeed.
They showcase the happy path.
The ideal workflow.
The intended use case.
And there’s nothing wrong with that.
Examples are important.
Documentation is important.
Tutorials are important.
But they’re also controlled environments.
The developer already knows what the outcome should be.
The architecture is simple.
The requirements are predictable.
The scope is limited.
Real projects are none of those things.
Real Projects Create Real Pressure
The moment a library is used for an actual project, the rules change.
Suddenly you aren’t building a demonstration.
You’re trying to solve a problem.
You have deadlines.
You have changing requirements.
You have content to manage.
You have layouts that don’t quite fit.
You have edge cases.
You have mistakes.
And that’s where a library starts revealing its strengths and weaknesses.
Not in the demo.
In the pressure.
Reality Exposes Bad Assumptions
One of the most valuable things a real project does is expose assumptions.
Assumptions that seemed perfectly reasonable while designing the library.
Assumptions that looked elegant on paper.
Assumptions that made sense during development.
Then reality arrives.
A workflow feels awkward.
A configuration feels repetitive.
A component requires too much setup.
An API doesn’t feel natural anymore.
The problem isn’t that the design was wrong.
The problem is that it hadn’t been tested against reality yet.
Framework Authors Need To Become Users
I think one of the best things a framework author can do is become a customer of their own software.
Not occasionally.
Not for demos.
Every day.
Build websites with it.
Build applications with it.
Build businesses with it.
Depend on it.
Because the moment you depend on your own software, your perspective changes.
You stop thinking like a framework author.
You start thinking like a user.
And users care about very different things.
Users care about friction.
Users care about clarity.
Users care about getting work done.
Features Stop Mattering As Much
One surprising lesson is that many feature discussions disappear once you’re building something real.
The conversation changes from:
“What features should we add next?”
To:
“Why does this workflow feel awkward?”
Or:
“Why did this take longer than expected?”
Or:
“Why am I repeating myself?”
Those questions often lead to far more valuable improvements than adding another feature.
Real Projects Generate Better Ideas
I’ve found that some of the best ideas don’t come from brainstorming.
They come from building.
You’re working on a real project.
You encounter friction.
You solve the friction.
A pattern emerges.
An abstraction emerges.
A better API emerges.
Many of the strongest improvements I’ve made to software projects didn’t come from planning sessions.
They came from trying to get actual work done.
The project taught the lesson.
Every Library Needs A Home
This is one reason I believe every library should have a real project associated with it.
Not as a marketing example.
As a proving ground.
Something that forces the library to solve real problems.
Something that depends on the library succeeding.
Something that exposes weaknesses before users do.
The goal isn’t to prove the library is perfect.
The goal is to create an environment where the library can improve.
Building The Ecosystem
As I continue working on KiwiEngine and the surrounding ecosystem, one thing is becoming increasingly clear.
The websites.
The documentation.
The applications.
The tools.
They’re not distractions from the framework.
They’re part of the framework.
Every real project creates feedback.
Every real project exposes friction.
Every real project improves the underlying system.
That’s why I believe every library needs a real project.
Not because it validates the library.
Because it teaches the library what it still needs to become.
Top comments (1)
Agree with this.
Examples validate that something works; real projects validate whether it fits reality.
Most API design problems only show up once composition, scale, and changing requirements enter the picture.
In practice, real usage ends up being the actual design process.