July 29, 2016 Javier Eguiluz

When the Symfony documentation was started more than 5 years ago, it was just a few short articles written by Fabien. Now, we boast more than 1,000 pages of documentation, a team of 4 maintainers and over 1,000 contributors!

As the project grew, we've tried to innovate: adding continuous integration to catch build errors, setup Platform.sh to auto-deploy every pull request and implemented a process so that all new features to Symfony's core become documented (an amazingly rare feat).

And just like with code, a project must challenge itself continuously to stay ahead of the curve.

In this article, we're thrilled to introduce the new Symfony Documentation: a result of over 150 hours of volunteer work via a secret project codenamed "Project Mercury".

What could we do better?¶ During a recent meeting with Symfony Docs maintainers (Ryan, Wouter, Christian and Javier), Ryan voiced a frustration and a crazy idea: I think the layout / organization of the docs on symfony.com is too confusing. I would like to completely restructure things. The problem? Historically, the docs have been divided into three major sections: "The Book" (several chapters explaining from basics to advanced features); "The Cookbook" (standalone tutorials focused on advanced topics); "The Components" (articles explaining how to use the Symfony components outside from the framework). But for newcomers, this is confusing. Where do you learn about Routing? Should you select Book, Cookbook or Components? In reality, every topic was spread out into these three sections. And it's challenging even for us: should the new Symfony Cache be explained in a book chapter, in a series of cookbook tutorials or just in the component itself? So, we decided to invest serious time and make a big change. That's when Project Mercury was born. We studied the documentation of the most relevant projects (PHP or not, framework or not, open source or not), added our own ideas, and found a new doc structure that we think is a huge step forward.

The new documentation structure¶ Symfony Documentation is now divided into two main parts: Getting Started , a short book that explains all the basics about developing apps with Symfony framework in just six chapters. This is the entry point for the documentation and this is the resource you should recommend for people who want to learn about Symfony;

, a short book that explains all the basics about developing apps with Symfony framework in just six chapters. This is the entry point for the documentation and this is the resource you should recommend for people who want to learn about Symfony; Guides, everything else. They are short and focused tutorials about a wide range of topics (email, databases, logs, forms, services, etc.) And that's it: no more book, cookbook and components. Every topic - from routing to security & serialization - has a single page that links to all related documentation. The new doc structure is flat and simple, instead of deep and nested. Compare the 2.3 doc structure with the 2.7 doc structure. The new structure may seem "less clean", but is easier for finding docs for any given topic (e.g. "anything related to routing"). You can experience the new structure in the revamped documentation index page.