Symfony2 Documentation

As you might have noticed, the Symfony2 documentation grows every single day. Since the Symfony2 Live Conference, I regularly publish new documents for Symfony2, like the best practices to follow for Symfony2 bundles.

I think it's now time for the community to provide feedback on the Symfony2 documentation on several topics:

  • The documentation strategy (instead of a large book, the Symfony2 documentation is split into small chapters about specific topics);

  • The documentation format (it should be easy and fast to read, easy to understand and straight to the point);

  • The documentation content (things can change; if you think that documented features can be enhanced or don't make any sense, please tell us);

Early feedback is the best way to influence the way Symfony2 will look like. So, take a day or two to read the documentation, test the framework on some simple examples, and give feedback.

Comments

I'll like much this way, you can go faster where you want to go, and where you find what you need !

It's better than the chapters of a book...
Hi

How about creating a public wiki for Symfony which is easily searchable and well categorized? This is easily update able and accessible to all.

Just a thought :-)...
typo in the title ! :p
Huge books with useless blablabla are a waste of time.

A simple how-to for each major feature to start (and without going too much into the details) and then, documents/articles/discussions about specific/advanced topics seem to me the best way to learn fast.

Remember this picture :
http://www.vinch.be/attic/books.jpg
I'd like to see some form of user contribution like Cornelius mentions.

Not sure exactly how, but comments like at PHP (php.net/string) or some form of wiki would be a starting point.
Should be not only reference like it is now, but also examples of good coding. A simple bundle, simple Ajax js usage, etc...
I have always found the full books useful, but am a big fan of the way the Symfony2 documentation is being presented. I think they can complement each other well.
Like Åsmund Garfors said - opportunity for the community to expand, or at least comment on, the documentation would be great.

There is so much knowledge on the web re symfony 1.x but it is widely distributed and occasionally hard to find. There will always be distribued knowledge on blogs, third party wiki's etc, but giving space in the official documentation for the community to document specialised uses and advanced topics, in a way that doesnt detract from the original 'official' documentation, would be great.
Small chapters will be better then book. Although "definitive guide" is must-have for newcomers.

btw. Configuration section in DoctrineMongoDB guide is incorrect.
+1 public wiki
I have yet to see a documentation wiki done right. It starts off as a good idea and in the end it looks like a rubbish incoherent documentation. Everyone has his own style of writing. Most of them are just incomplete or outdated. No one has time to correct anything.

I really like this documentation approach. Now, I'm not an impressive Symfony user, and then, this doc allows me to understand standard concept with valid example and schemas...

Personnaly, I think that wiki is not a good idea because a technical documentation need to be grown by devlopment team and not by users...

I wait impatiently a dummy project like Jobeet to use this new version!
I'd really like to see users comments in the documentation and maybe an example site like Qcodo framework has (http://examples.qcodo.com/examples/) in which you can see a live example and the php code used for acomplish that functionality. Maybe like a live cookbook .
A way for us to know that new documentation has been added or existing ones have been updated.
Definitely prefer this method of documentation over the current (series of books) method of documentation for Symfony 1.4.

As per a discussion in the symfony-dev groups, I still recommend a "comment" system like php.net has (that is obviously moderated) with the latest comments displayed first.

I believe any other "user contribution" should be separate from the main documentation provided by the Symfony2 team - but a user contribution method should be implemented.
+1 for wiki

I think the new documentation is going in the right direction. It's also equally important to have a Practical Symfony-like book that walks newcomers through.

Something that's been lacking is the wiki - being able to have a place for users to post code snippets or other aid for the rest of the community helps everyone and fills in gaps where the documentation may not cover.
+1 for wiki

there is no very big difference between small chapters or book with chapters
documentation will be more useful if there will be user comments for each chapter were user can put examples of code how they use it (for example php.net have user comments for each function and it's really useful)
+ useful search is very important it helps save time.
+ better navigation between topic and sub topic helps save time too
At the moment documentation is not very useful for me. Content is OK but navigation is no really useful.
I would like to mentioned that i choose Symfony 1.0 because of its complete and solid documentation. The only "foggy" part was behaviours. But starting from 1.2 there are a lot of issues that you have to google for a blog or something to find documentation. IMHO a nice book like "definitive guide" is a must, after almost 3 years building projects with symfony in 2.0 i fill like a new comer again. The Chapter method of Symfony 2.0 documentation is good and it would be even better if the was a pdf version also (for ebook reader or paper). An other think is documenting "extenting symfony" a little more. That fast chapter in the book was like an announcement :D Events, plugins, behaviours and so on.
User contributed messages like in php documentation would be a great enhachment, personaly i find more userfull user comments that doc it self.
Keep improving the best php framework in the market but please document it more there are old dogs out there that need it.
The Symfony 2 "Quick Tour" is great so far. The guides as well, assuming that the potential readers now are primarily symfony 1.x users throwing an eye into how things will look like in Symfony2.
But once Symfony2 will be released, the big audience will be the broad web dev community not yet working on symfony. Addressing these will work out better with book-quality documentation like the "definitive guide" or "practical symfony" etc.
Not to underestimate: such professional books serve as a business card for Symfony as an open source project, emphasizing that Symfony is a solid thing providing a real added value. (I may be old-fashioned though, but hey, everything's marketing!)
With regards to contents, I'm in favour of books as they do provide a pre-defined common thread ("file rouge"). Documenting Symfony2 only on a wiki would be far less optimal, as its articles may be authored with individual things in mind, leading to a rather (too much) cluttered whole, thus may look like a bit a misty thing (my marketing view again... ;-).
Cheers! R.
I also think that a book-like documentation is the way to go for symfony2
I think there are two types of learners: top-down and bottom-up. The top-down guys like to read the technical, theorical documentation, to know every detail about the framework's architecture, and then experiment with it. The bottom-up students prefer to get practical - they install the sandbox and start playing with it right away, consulting documentation as they see fit.

I believe the documentation should consider that. IMO the best way would be to have something like the sf1.0 book for top-down learners and something like jobeet docs for bottom-up learners.

The current "tour" docs try to mix both by giving a little theorical info and then some practical examples. Personally (being a top-down learner myself) I think that format makes it harder to see the framework as a whole - how things fit together -, which is the first step for writing clean apps.

I believe php.net-like comments are useful and add a lot of value to the documentation, but I wouldn't go as far as opening a wiki as it might get a bit messy (or generate a lot of moderation work by the team).

Obviously, the API and Reference docs are necessary - their current format is good enough IMO.

Keep on the good work!
What is really important for me is a complete performance guide.
I think Thiago makes a great point. I was never a fan of Jobeet/Askeet. I prefer something like The Definitive Guide/A Gentle Introduction backed up with a separate book or appendix like the Reference Guide. Id also lend a +1 to a comment system directly on the online versions of the docs similar to php.net.

A key issue I had with the 1.0 docs was that critical info was spread across the book, Askeet, the wiki, forums, and mail list. While i obviously made it through it was a huge time drain when first learning.
If u want good example of user guide, take a look at codeigniter userguide. this is their strength gaining new userbase.
Marius wrote:
"If u want good example of user guide, take a look at codeigniter userguide. this is their strength gaining new userbase."

Because of his comment I had a look on the docs of codeigniter.

Very, very well done!
The docs and their index are well structured and clear. The chapters
Basic Info, Installation, Introduction, General Topics (detailed Feature / information per theme), Class Reference, Helper Reference, Additional Ressources
are quite complete!

There is nothing to miss.
If you look on a page, e.g Controllers, first thing you see is a per page index:
- What is a controller
- Hello World
- ...

Great!
While reading the documentation, there are currently some important points missing:

First of all, an index/overview at the beginning of a chapter (e.g. Quick Tour: view). The index should be a structured linked list.

A second point are missing hyperlinks within the chapters. E.g. in Chapter 2.3 you write about "Including other Templates". Suddenly the render() method is explained. Uups, didn't you want to talk about the technique to include other templates? It is ok to mention the render() method to explain the example code, but it should be linked to some place of a reference where it is explained in detail.

Last but not least, on each chapter you should have a short overview of its content and its goals.
And this should be something else than "yes it is powerfull ..." or "look, did not take you 20 minutes so far".
For the view it should be a short discussion of the main concepts, which are described in detail later.

What do you think?
Hi,

while diving deeper into symfony2 (or should I say: while trying to dive deeper ...), there are other essential things missing in the documentation.:

- Bootstrapping:
A Guide to Bootstrap your application. What does the dispatcher actually do, which config files are read, and where is the suitable and centralized place to initialize components?

- database setupb
no word about this in the docs so far (beside the doctrine chapter, which cannot be seen as a database guide).

- multiple connections
How do you setup - and - handle multiple connections with symfony2 ?

@rooki: Keep in mind that Symfony2 is not even in alpha state. We are well aware that lots of documentation still need to be written. With the upcoming release of PR3, we will have more documentation.

Comments are closed.

To ensure that comments stay relevant, they are closed for old posts.