dsyph3r/symblog-docs — Issue #4: Simplify Tutorial Part 1
Author: lazaridis-com
Created: 2011-12-26 18:10:21+00:00
State: open

I suggest to simplify the tutorial a little bit, with the goal:

a) to enable a simple user to get things up running quicker (hours instead of days)
b) to enable an expert (familiar with web/OO etc.) to make an incremental teach-in, based on the same tutorial
c) to align the tutorial to the contents of the original quick-tour (http://symfony.com/get_started)

Especially at the start of the tutorial, things should "come to life" very simple, avoiding this way reactions like "what's this? Why it's so complex". Some contructs are needed only within larger projects and teams, there's no need to showcase them in the 1st chapter.

This would mean to make the following changes (example for Part 1):

MUST:

1.) use the defaults from "generate:bunlde", which is "annotation"

benefit: avoid complexity, keep design model-centric. Routing-info in external files can be introduced later

2.) instead of deleting the "DefaultController" & files, use them as a foundation

benefit: usage of defalult generated files is more convenient and reduces steps.

Note: if it is a sort of convention to use "Page" for pages, then a way should be found to generate the bundle immediately with the PageController instead of DefaulController. Alternatively, the DefaultController stuff can simply be renamed.

SHOULD:

3.) avoid external dependencies (e.g. js, fonts from google), thus tutorial is self-contained and runs off-line, too.

4.) symfony2 welcome screen route should not be removed, but rerouted (e.g. prefix /welcome or similar)

5.) Suggesting a new user to create 3 files for a simple about page does not convince much about the usability of the framework. Personally I would expect default-routes. If not: declaring the route via metadata on the aboutAction() in the controller reduces the necessary coding to 2 files (experts still can use external routing if they have the need).

6.) initial use of sqlite instead of mysql, to simplify requirements.

benefit: allow interested people to evaluate Symfony2, even if the don't have all the tools setup.

-

I hope that the benefits become clear.

(After agreeing to the changes , I could workout the text an send a pull-request in)