Sometimes, Sylius invents new ways of doing things in open-source development, and this might be one of those times.
You might remember when Domain-driven Design (DDD) was hyped up in the software world. Well, they've adapted that concept to create something they call "Documentation-driven Development" - and it's changing how they think about building features.
What was the challenge?
As Sylius grows, it faces a familiar problem: technical debt can accumulate with every new line of code. More features mean more complexity, more code to maintain, and more tests to write.
The bigger issue? When introducing new features, they think about users as a whole. Some want Sylius for scenario A, others for scenario B, and sometimes these scenarios conflict with each other.
Take international URL structures as an example. Some stores prefer a single domain with country codes like store.com/pl, while others want separate domains like store.com, store.de, store.pl. Supporting both approaches would require complex routing logic, substantial code, and ongoing maintenance.
However, when Sylius asked themselves how many users actually need to customize their URL structure, many said they'd be fine with the default country code approach. Yet there's still a significant percentage who want to change that.
Instead of building an admin panel feature that would eat up development time and add more code to maintain, they decided to write documentation for it. Since their users are developers and Sylius is open-source, they have the necessary skills to implement clean code changes themselves.
If they can describe in a few simple steps where to paste a specific code snippet to change how country codes work in their domain, why not create documentation instead? Interested users can read exactly how to do it.
There are many such places in Sylius, which is why they've committed to creating documentation for solutions that aren't covered by Sylius core but could still be important.
https://bitbag.io/blog/how-to-avoid-technical-debt-in-sylius
The "Frankenstein" problem
Instead of getting caught up in patch cycles and releases, spending too much time on seemingly simple features, Sylius takes a different approach. Adding too many edge cases to Sylius core would turn it into a "Frankenstein" - hurting performance and increasing complexity.
These problems disappear when you give people instructions on how to implement or modify something themselves.
Here's an example: they had a system handling large orders where customers might purchase thousands of items at once. This caused performance issues during checkout. Instead of adding toggle switches to put the cart into a different performance mode, they wrote a simple piece of code that modifies one file and adds a basic rule. Result? 90% performance improvement in the cart. Zero releases, zero additional core code, zero new tests, and the ability to revert the change at any time.
It's worth exploring places in Sylius where the system can perform much better, not by writing new features, but by looking for areas that can be improved, measuring behavior, and documenting solutions through short how-to guides. Sylius users don't always expect everything to be available in the admin panel as a new feature. Often, they just want instructions on how to do it.
<div class="rtb-text-box is-blue-100">Think of it like LEGO blocks - from the same set, you can build several other things.</div>
How Documentation-driven development works
The concept is called Documentation-driven development in Sylius, and it aligns perfectly with how much new content they've introduced to Sylius documentation. The quantity and quality of Sylius documentation have multiplied in recent months, and this is just the beginning.
Their process resembles Test-driven Development, but with documentation. Sylius tries to solve an issue by writing documentation first, which immediately tells them whether they have the correct code in the right place. On the flip side, if writing the first few pages of documentation feels difficult, it might mean they made a mistake somewhere or the approach needs improvement.
They recently had this exact situation while writing documentation. The thought emerged: "If someone wants to implement this simple thing, why do they need to make so many modifications?" This led them to discover a simpler way to implement the functionality, and the documentation ended up being just one page.
This process perfectly shows them whether they're heading in the right direction or if something needs improvement in a given area.
The numbers don't lie
Looking at static code analysis, Sylius has around 12 times less code than Magento. This makes it easier for developers to navigate and learn how everything works, especially when it's written in a clean, structured way. Adding thousands of new lines increases complexity and the potential for drowning in technical debt.
They see the potential of this approach, and the idea is becoming better rooted in their team. It's making their documentation better and changing how the entire team works. Before a feature gets added, they first try to write documentation for it, then consider whether it needs improvements, whether it should become a plugin, and finally, if the problem it solves is universal enough, whether to add it to Sylius core.
When a feature goes through this process, its code gets tested multiple times, ensuring the highest quality solution.
https://bitbag.io/blog/understanding-coding-standards-best-practices
Better control over development
What's more, Sylius gains better quantitative control over everything. If they write documentation, they can see how many people have visited it. If they release a plugin, they can check how often it's downloaded or installed. This means nothing enters Sylius' core by accident.
They believe that increasing the quantity and quality of documentation will also help train AI solutions, which can then assist many developers working with Sylius. The more complete their documentation gets, the better language models perform with it, making tools like GitHub Copilot much more effective for Sylius development.
{{cta-technology-sylius="/comp/cta"}}
The formula for the future
Here's their bet for building the future of highly flexible eCommerce platforms: Lightweight, flexible core > Documentation > Feature overload.
Does this mean they won't be adding new features? Quite the opposite - they'll be doing it more than ever. But they'll be doing it smarter, ensuring each addition truly belongs in the core rather than in a how-to guide.
This approach keeps Sylius lean while making it incredibly powerful for those who need specific functionality. It's about giving developers the tools and knowledge they need, not dictating exactly how they should use them.
The documentation-driven approach isn't just changing how they build Sylius - it's changing how they think about what open-source platforms should be. Sometimes the best feature is the one that teaches you how to build exactly what you need.
div class="rtb-text-box is-blue-50">👉 Sylius documentation</div>
