Introducing the new Symfony Documentation
July 29, 2016 • Published by 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;
- 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.
Why did you call it "Project Mercury"?
Because codenames are fun :) and because Mercury is the Roman God of communication and eloquence. What better name for the clarity we hope to bring every day to Symfony users.
Help the Symfony project!
As with any Open-Source project, contributing code or documentation is the most common way to help, but we also have a wide range of sponsoring opportunities.
Comments are closed.
To ensure that comments stay relevant, they are closed for old posts.
The documentation organization seems to be so much easier to access.
Thanks a lot for this improvement.
I was wondering if it could be relevant to add some new chapters about subjects not concerning Symfony functionalities themselves, but on how to build apps with it. Symfony has always been great when it comes to the use of best practices for building apps and that.
I am thinking about a basic guide on Behat / Mink integration for a Symfony app, a guide for producing a basic standard REST API application (either with Dunglas Core Api platform, or with FOSRestBundle). I'm talking about REST API, because the documentation still have a strong MVC approach, despite the rise of service oriented apps.
The idea would be to show to newcomers that Symfony can easily meet their needs for any kind of modern application and that beyond its technical capabilities, it is a framework that promotes best practices. There are many tutorials about the subjects I mentioned, but a starting point could be welcome.
On the other hand, some parts could probably be shortened (e.g. the use of APC, which is now built-in with all PHP versions Symfony 3.x supports).
Not sure people would agree with me, but I really like the way you try to think like a newcomer, and I try to do it as well!
In any case, each new topic should be considered separately. We cannot add a ton of new articles because they require maintenance and our resources are limited. The best strategy would be to open issues in https://github.com/symfony/symfony-docs/issues to discuss about the next articles to add.
Thanks!
So ... do you plan to merge this huge work on the actual repository ? Else, do we have to re-submit contributions from symfony-docs to this new project when it will be opened ?
> The idea would be to show to newcomers that Symfony can easily meet their needs
Big +1 on this, by the way thank you to companies who sponsor it and to Wouter de Jong!
Mickaël
The private repository was used just to avoid all the noise and chaos generated during this doc reorganization.
And anyway, a documentation is about "How to " do things, so no need to repeat it at the begining of each article.
For example :
How to Authenticate Users with API Keys => Authenticate Users with API Keys
How to Choose the Password Encoder Algorithm Dynamically => Choose the Password Encoder Algorithm Dynamically
Using pre Authenticated Security Firewalls => (stay the same ;) )
The search engine shows the old and unmaintained 2.1 version as the first result, we have to scroll to the relevant results: http://symfony.com/search?q=collection Unmaintained versions may be displayed with a different color or even hidden, for example one year after the EOL.
Can you merge similar search results and provide one link per version?
The search engine is also highlighting fuzzy matches, for example it highlights "text" when I'm looking for "test", that's confusing: http://symfony.com/search?q=collection+test
Are this two new docs are downloadable as PDF ?... and what is the future of actual PDF, no more updates ?
Thanks.
@troudbal the old PDF will remain (e.g. "The Book" for Sf 2.3) but they won't be available for newer versions (e.g. "The Book" for Sf 2.7 will disappear). And yes, we'll add very soon the new PDF contents.
@Richard it's true that some articles need some updates. We couldn't reword/update all of them in time. "Debug" is definitely one of them.
A minor improvement would be to keep the guides menu open whenever reading a topic under it. At the moment, it is always the Getting Started menu that is active.
@Dario thanks for reporting this issue. It has been fixed and it will be available after the next deploy.
but need to keep the components book in the way it used to be cause not all newcomers are willing to use the whole framework, instead the components they just need...
How will be structured the new pdfs? old fashion? new way?
There will be pdfs at all??? (since I didnt see those).
Will be the new "guides/cookbook" organized in new pdfs?
Just a shy question, whether offline/pdf download will as well be available in the new documentation structure?
I link to the request/response article and the flat file article all the time. Now it seems difficult to find them. Pretty much have to know where they are. There does not appear to be a /introduction page anymore.
I'm probably missing something very obvious but those two articles were one of the main reasons I decided to invest time in Symfony way back when.
@Roland we did that in the past (e.g. http://symfony.com/blog/a-month-of-symfony-documentation-7-june-2015) but discontinued it because it's a lot of work. But we maintain a full CHANGELOG of the changes introduced in the docs: http://symfony.com/doc/current/changelog.html
Gran Trabajo!
@javier gracias por su esfuerzo. Realmente importante.