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.
