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.
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
Comments are closed.
To ensure that comments stay relevant, they are closed for old posts.
It's better than the chapters of a book...
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 :-)...
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
Not sure exactly how, but comments like at PHP (php.net/string) or some form of wiki would be a starting point.
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.
btw. Configuration section in DoctrineMongoDB guide is incorrect.
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!
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.
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.
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.
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.
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 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!
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."
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!
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?
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 ?