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.
Wow! Great job guys!
The documentation organization seems to be so much easier to access.
Thanks a lot for this improvement.
Congrats for the hard work! It's awesome and the new approach is certainly less misleading for newcomers.
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!
@Michaël we'll definitely add new guide about different topics. Your own proposals look good and the new doc structure allows us to introduce very different topics without "breaking" the other doc articles.
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 ?
Big +1 on this, by the way thank you to companies who sponsor it and to Wouter de Jong!
Mickaël
Congratulations for this great work, documentation is a key point in any open source project. Thanks to you Symfony stays on top!
First thing I did: CTRL+F -> rest. No results found. I think it is a pretty important topic in the SPA / mobile apps era.
@Mickaël yesterday Christian merged all the private repository commits into the public one. You can see for example the new doc structure for "master" branch: https://github.com/symfony/symfony-docs and you can see the commits for that branch too: https://github.com/symfony/symfony-docs/commits/master
The private repository was used just to avoid all the noise and chaos generated during this doc reorganization.
@Giacomo we agree with you completely! REST and APIs are the topics we need to work next. Thanks!
I would suggest to remove all the "How to" in the title of all the articles. Indeed, now there is a mix between article starting with "How to " and other that do not (e.g. http://symfony.com/doc/current/security.html#learn-more)
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 ;) )
@Vinorcola that's actually a tricky question. We were mulling over the idea of adding "How To..." for all articles. And if we decide to remove it, there's always the divide about using "Choose the ..." and "Authenticate Users..." or "Choosing the ..." and "Authenticating Users..." We definitely need to think deeper about this!
Great work!
Awesome!
Great job guys!
This could greatly improve onboarding of newcomers. Thanks a lot, can't wait to check it.
Showing the search field at the entry point of the documentation is nice, but there's room for improvements:
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
Oops, I missed the filters at the left of the page, that's really useful but it still thinks that the old and unmaintained versions should be displayed differently or hidden.
Great!
Hi, we mainly use Symfony pdf documentations for offline use (bercause no internet at work). Are this two new docs are downloadable as PDF ?... and what is the future of actual PDF, no more updates ?
Thanks.
Great work guys! Only having two main parts was clear for me right away, the 'tag cloud' was a bit unclear though (I liked 'cookbook' better). Pages like 'debug' only have one article, so maybe the tag cloud can be improved a bit?
@Alexis you are right. The search engine needs some updates. We have some ideas to better integrate it in the docs. Regarding the quality of the search results, we're waiting for Algolia to fully update and reindex the new docs and remove the old docs.
@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.
Not to nit pick but the article implies that there will no longer be a Component section and yet, there it is. Personally I kind of hope you keep the components section for the non-framework developers.
Great job guys! One note only, on home page (symfony.com) there are now two links that return 404 (the symfony book and cookbook tutorials).
Awesome. Congrats for the amazing work. 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.
@Art there is a main article listing all the components ... but each component page now only shows how to install it and "the Hello World example" for that component. The rest of articles have been moved to the "Guides" section because they are mostly the same when using the component inside or outside the framework. For some specific cases, we've maintained separate articles for components and the framework.
@Dario thanks for reporting this issue. It has been fixed and it will be available after the next deploy.
@Tito that's a very nice suggestion! We've already implemented it and it will be available after the next deploy. Thanks!
Prettily done! It's a vast improvement on what was already very good documentation. To all involved, thank you.
Its great just for newcomers! 4 thumbs up for this. 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?
Oh my God! Great job, guys!!! Thanks a lot!
At first I was a bit confused since I was used the previous structure, but this is much better actually. Looking for some specific chapter of Symfony on two places - book and cookbook is actually confusing for people new to Symfony. Great work.
This is a great improvement! Thank you!
Do you guys have plans to address the broken links? I found out about the reorg the hard way - I clicked a link from Google. Maybe a 404 page with "did you mean ..." type thing? I was able to find what I was looking for, but newcomers may not be able to.
@Micheal you are right: most of the old pages are correctly redirected to their new location ... but there are still some errors to fix. We're on it!
Do you have a plan about documentation translations ?
@Hidayet we decided to discontinue the official translations a while ago: http://symfony.com/blog/discontinuing-the-symfony-community-translations
GG guys :D
Greatly appreciated! Just a shy question, whether offline/pdf download will as well be available in the new documentation structure?
Wow! Great work!
Great work! As we are talking about doc, what do you think about always making the left table of content visible (sticky content) ? it's always handy to view it at a glance.
Missing introduction section?
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.
@Javier Eguiluz would you consider adding a list of recently added/updated articles? Especially recently added would be awesome!
@Raphael yes, we'll introduce PDF for all the contents. Sadly it will take some time.
@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
@Javier Eguiluz Oh wow :) Still an RSS feed of recently added articles would really, really come in handy. But im assuming you'd have to built that to make it work dynamically... which is definitely worth the effort imho.
Nice work. After two weeks of new doc usage, I no longer get lost in documentation.
Great Work!
Gran Trabajo!
Thanks very much. This is a very important tools.
@javier gracias por su esfuerzo. Realmente importante.