[Index] Use-cases on the index

[tgalopin]

Hi!

I'm quite new witht Symfony CMF and I don't know it very well. I also know that it's difficult to write clear documentation about something when you work on it and know it very well. So as I have a few problems with understanding Symfony CMF from the documentation, I'll try to explain my problems here.

My first and main problem is organization. While the documentation stores a lot of informations, these informations are dispatched in many different pages and not always complete. Take for instance the core bundles installation. This page does contains very useful informations: how to install the bundles in an existing Symfony app. However, this page is hidden in the Cookbook, difficult to find and access. Moreover, it's not even complete as the documentation does not include the SonataBlockBundle and PHPCR configuration blocks.

My second problem is the website. It's the first result on Google for "symfony cmf" but it does not provide a clear, straight-forward homepage. I think the first thing we should read on the website is a short introduction of Symfony CMF (mainly aims IMO) and how to get started easily. Currently, the only documentation link is very small ("Get started" in "Try it out") and the homepage explain way too much things.

I discussed it with @dbu and @lsmith77 and we agreed on the following idea: instead of having a big index containing all the information (a book, a cookbook, a quick tour, tutorials, specific documentation for bundles, etc.), we think it would be better to have different index pages for specific use-cases linkings to documents in the documentation

For instance, we could have the following use-cases:

• I want to try Symfony CMF very quickly -> sandbox
• I want to start project based on Symfony CMF -> standard edition
• I want to integrate a very simple CMS in my existing Symfony application -> SimpleCmsBundle
• I want to create a CMS on top of Symfony -> independant bundles

Eeach one of these use-cases could be put on the website homepage (with a bit of redesign to create big blocks for instance) and they would all consist of an ordered list of things to read in order to achieve the goal.

I think it would be much easier to understand and use Symfony CMF by doing that.

[dbu]

i like this idea of triage for the readers, thanks for suggesting it!

@wouterj what do you think? are these use cases the main use cases? and are the answers the right answers? i could imagine the 4 cases as a two column table so we get a grid and let people choose which introduction they want to read, and which access to the documentation they prefer.

the links to the bundle docs from sandbox / SE entry points could also go directly to configuration, skipping the installation bit as that is already done in the SE / sandbox...

[tgalopin]

The more I think of this problem of documentation, the more I think the biggest issue is actually that it's not clear in minds of people what the Symfony CMF aims to be (it wasn't really clear to me before I spoke with @dbu and @lsmith77).

I talked a bit of that with other people, especially Django people that know Django CMS well, and when they see Symfony CMF without knowing Symfony very much, they assume Symfony CMF a bit the equivalent of Django CMS for Symfony. So when they try it, they are disappointed as it's not what they thought.

I think a clear short sentence explaining that Symfony CMF just aims to be a set of reusable bundles to create your own custom CMS would be a big step forward (and also explaining that SimpleCmsBundle is an example of such CMS built on top of CMF bundles).

If we do a website with four use-cases as we discuss here, such a sentence should be the big, bold, hightlighted text we see as soon as we arrive on the website.

[ElectricMaxxx]

As described in #700 i got the same feadback talking guys at the FrOSCon. So i would prefere a documentation, which describes it more from the Use case point. In generell i would call that cookbook, but would put that in the front.
The other point is an den image problem. We need to avoid that poeple think, the CMF is a CMS.

[ElectricMaxxx]

i would like to add the following use cases:

• having an working Symfony Application, where i whant to add some static pages
• having a working Symfony Application, where i whant to add some blog functionality
• having a working Symfony Application, and wanna use some dynamic routing

[tgalopin]

I totally agree @ElectricMaxxx, but I think we should explain directly what is dynamic routing instead of calling it like that in the title. As a newcomer, I probably don't know what dynamic routing is.

[ElectricMaxxx]

For sure. A soft entry point would be moving from the standard static symfony way to a persisted solution without ever mentioning the PHPCR. I think that is the way the cookbook goes.