Introducing the new Symfony Documentation

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:

1. "The Book" (several chapters explaining from basics to advanced features);
2. "The Cookbook" (standalone tutorials focused on advanced topics);
3. "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;
• 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.

How we did it

But restructuring the entire documentation? That would be a daunting task and require a huge amount of work. That's why Ryan proposed another crazy idea:

Let's convince our employers to "invest" in Symfony by allowing us to work on "Project Mercury" for an entire week.

And they agreed! KnpUniversity sponsored Ryan's work, basecom sponsored Christian's work, SensioLabs sponsored Javier's work and Wouter dedicated his own personal time. In total, more than 150 hours were spent on the update.

A big thank you to those companies for supporting the Symfony project with such a big investment of resources.

Because we were making so many changes, (almost every file was touched), we worked on a private repository. This allowed us to work quickly and avoid any confusion on the public docs repository during the process (e.g. "why is half of the book gone!?").

In addition to the new structure, we had time to focus on a few other things:

• Many articles were shortened, simplified and re-worded: we actively moved long explanations into their own dedicated pages and linked to them. For example, when you're first learning about forms, it's counter-productive to include almost 200 lines of details about validation groups. That now has its own article.
• We also continued a trend to include more comments in code examples, instead of long paragraph explanations.
• We added several improvements to the styling of the docs, like updating the terminal code-blocks to be more obvious and several other changes. We also closed several issues reported on the public symfony-docs repository.

Of course, when you move hundreds of documents and deal with hundreds of thousands of words, there could be some mistakes. If something looks weird or is much harder to find, open an issue to let us know.

And a special thanks to Fabien for helping to merge the necessary changes to the Symfony.com infrastructure.