Hi Fabien, Thank you for the complete and descriptive response; we really do appreciate it. Just to give my take on why the Definitive Guide is so good. Its for one of the reasons that you mentioned, that its easier to find a description of the various aspects as the Practical guide looks at symfony from the perspective of a single application. One of the biggest reasons I like the Definitive Guide isn't because it was 100% definitive (so feel free to change the name if you like) but the fact that it at the very least covers most of the symfony framework even if it references to another source to get more complete information. The Definitive Guide is something you can read from start to finish. Its a great way to get "clued up" on what symfony's capabilities are and not necessarily every implementation of the framework. Its a far more general look at what makes symfony tick, rather than the very application specific nature of the practical guide, but also doesn't go too deep into implementation that people feel a little lost, like the Advent calendar and API documentation can be.
If I just read through the Definitive guide I'll understand in better detail what the Advent calendar documentation is referring to, as well as understand why a specific feature of the Practical Guide application was coded a specific way, to all the way into understanding the various interactions between the classes described in the API docs better without having to guess as much. We in fact still use the Definitive Guide to train new developers into the world of symfony. Thanks for taking the time to work on it and I will definitely look into how I can contribute updating it further. On Mon, Jan 25, 2010 at 4:22 PM, Fabien Potencier <fabien.potenc...@symfony-project.com> wrote: > Hi all, > > I'm listening... but I needed some time to think about the topic a bit more > before answering. Here are my thoughts. > > But before I start "ranting" about the definitive guide, remember that all > the work done on symfony is benevolent. It's true for my work, but also for > the work of the many volunteers that help build the symfony community (all > the core team members, the translators, the great people answering questions > on the mailing-list, forum and IRC, people using symfony and spreading the > word about it in their companies, people blogging or tweeting about it, and > many more). But as days are only made of 24 hours unfortunately, we need > even more help. > > Please, read ALL the information contained in this email BEFORE replying ;) > > The symfony core team, some great authors, and the translation teams spent a > lot of time writing and translating documentation for the latest versions of > symfony. And as a matter of fact, the symfony 1.3/1.4 versions are probably > the most documented versions of symfony, ever. > > Want to get started with symfony? read the "Getting started" guide. > > Want to learn symfony step by step? read the "Practical symfony" book. > > Want to find everything about configuring symfony? Browse the "Reference > guide" book. > > Want to learn what changed in the recent versions? Read the "What's new?" > and "How to upgrade" tutorials. > > That's already a lot of documentation for beginners and advanced users. > > If you have a closer look, almost all the information found in the > Definitive guide is available in one form or another in another piece of > documentation I've just mentioned. > > But people keep asking me about the definitive guide. I don't really > understand why, perhaps because of the title, or because it was the first > available book. I really don't know... (ok, I'm lying a bit here) > > That said, I hear the complaints. And so, last week-end, I have re-read the > definitive guide cover to cover. > > From my point of view, here are the main pros of the definitive guide book: > > * More time is spent describing the philosophy of the framework in the > first two chapters (introduction to the MVC model, ...). > > * Each feature has its own chapter or section in the book. Looking for a > specific feature documentation is easier (in Practical symfony for instance, > it's more difficult to find things are they are described in the context of > an application creation). > > and the main cons: > > * Difficult to learn symfony with the definitive guide as there is not a > single example described from start to finish - only snippets of code are > shown (the Practical symfony book is better in that respect). > > * Slightly outdated best practices (the Ajax chapter for instance, globally > installing symfony with PEAR, and many other small things): the web evolves > fast and things that were true four years ago are not true anymore nowadays. > > * Far from being complete or definitive. A lot of things are just not > covered by the definitive guide (the mailer comes to my mind, but many other > things are not even mentioned). > > That said, the book is not that outdated. And for good reasons. The symfony > core team have spent a lot of time during the last few years updating its > content for each new version of symfony. So, it's mostly already up-to-date > for symfony 1.2. The good news is that symfony 1.3/1.4 is not that different > from symfony 1.2 either. > > So, today, I decided to spend some time to update the definitive guide for > symfony 1.3/1.4. The good news is that I have already updated most of the > book content. I still need to work on Chapter 3 and 8 before committing this > new version of the book, probably later this week (or even today if you give > me some encouragement ;)). > > The following chapters are more tricky to update as they need a lot more > work: > > * Chapter 8 - Inside The Model Layer: It only talks about Propel, and about > a slightly outdated version of it. We also probably need to add a similar > chapter for Doctrine. And the Propel vs Doctrine problem is also present in > a lot of other sections of the book. > > * Chapter 10 - Forms: This chapter must be rewritten from scratch to > describe the new form system. > > So, here is my proposal if you want to help us. > > As said before, I will update all the chapters, except 8 and 10. This > version will be made available as a starting point for a more collaborative > approach to the update. From there, if people want to give a hand at > updating the book, please subscribe to the symfony documentation > mailing-list (http://groups.google.com/group/symfony-docs), where we will > coordinate the efforts (I cross-post this to the doc ml). > > You don't need to be symfony fluent to help updating the book. We need > people for a lot of different tasks: > > * help proof-read the modifications > * test snippet of code with symfony 1.3/1.4 > * spot missing things > * spot things that are not true anymore > * ... > > Fabien > > -- > Fabien Potencier > Sensio CEO - symfony lead developer > sensiolabs.com | symfony-project.org | fabien.potencier.org > Tél: +33 1 40 99 80 80 > > On 1/25/10 2:01 PM, Massimiliano Arione wrote: >> >> The question arose many times, but unfortunately there's no solution >> for now. >> Once I also asked if we can translate the book, since we already did >> it for the 1.0/1.1 version (it's in the wiki), but Fabien replied >> negatively. >> I think the book it's not in the plans of documentation anymore, maybe >> for "political" reasons? Of course, only Fabien can reply. >> I saw many moans in symfony forum about that.... I think we should do >> a collective effort to take this problem to attention of core team: we >> can keep to write here, but also write in forum and in the >> documentation group >> >> Massimiliano >> > > -- > You received this message because you are subscribed to the Google Groups > "symfony users" group. > To post to this group, send email to symfony-us...@googlegroups.com. > To unsubscribe from this group, send email to > symfony-users+unsubscr...@googlegroups.com. > For more options, visit this group at > http://groups.google.com/group/symfony-users?hl=en. > > -- Gareth McCumskey http://garethmccumskey.blogspot.com twitter: @garethmcc -- You received this message because you are subscribed to the Google Groups "symfony users" group. To post to this group, send email to symfony-us...@googlegroups.com. To unsubscribe from this group, send email to symfony-users+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/symfony-users?hl=en.
