Framework: Single Installation Track

[weaverryan]

Hi guys!

I'd like to think through the "getting started" process very quickly, find a nice, single user-flow, then make changes to match that flow.

This "single" flow will also mean that we remove duplicate installation docs. Right now, I know of these:

• symfony.com/download (create-project method)
• best-practices/creating-the-project (installer)
• quick_tour/the_big_picture (installer)
• book/installation (create-project method)

This is a meta-issue so we can (quickly) figure out what one well-thought-out flow might be and then execute it! Plan then execute! Go!

What a new user needs to get done

A) get the symfony installer
B) get composer (preferably a global install) - is not needed immediately
C) check system requirements
D) create a new project
E) start their web server
F) (maybe, if they don't use server:start) permissions fixes
G) get pointed to a nice getting-started tutorial (i.e. quick tour)

Proposed user flow:

1. We point the user to always start at symfony.com/download. If they go to symfony.com, they will see the big download button. If they're on the "Quick Tour", we'll point them here (and say, come right back afterwards). This page will take care of (A) and (D)

2. They use the installer. This will take care of (C) and should have a link that points beginners to the quick tour (G) (it already has, and should still have a link to the main docs)

3. The quick tour will guide them through (E) (the installer shows this too), take them through some initial cool stuff, then tell them to continue with some part of the book, based on what they're building (e.g. forms-heavy, Doctrine/db stuff, building an API). It can also have a quick link to the installation chapter in case you want to use Nginx/Apache - so this will take care of (F).

I think it's at least a nice step forward, but any other ideas are welcome.

TODOS

• a) The symfony.com/download page needs to be updated to show the installer (@javiereguiluz is working on this)
• b) Some details exist somewhere (small link on symfony.com/download that rolls down a hidden section or links to a standalone page on the docs) that shows the create-project manual method (download composer, check requirements, etc).
• c) Remove most of the installation chapter in the book - just point to symfony.com/download and keep the section about permissions and have a few details on where to go next (e.g. quick tour for beginners, other pages for seasoned devs)
• d) Remove specific installation instructions from best-practices document - we should just say that you should use the "installer" then link elsewhere.
• e) Remove specific installation instructions from the quick tour and make it point (in a non-confusing way) to symfony.com/download
• f) Re-read the quick tour once again and make sure it's something that helps get users started, have some success and (most importantly) gives them the proper directions on where/what to do next.
• g) Update http://symfony.com/doc/current/index.html to have a little spot at the top that says something like "Getting Started? Try the (link)Quick Tour(/link)"

Thanks!

[javiereguiluz]

Thanks Ryan for preparing this nice roadmap. Some points have been tackled in #4811.

I'm still thinking about your proposal of creating a very complete Download page and link to it from the different documentation resources. That would mean to create a very long and complex Download page. Doing that it's probably the best way to consolidate all this information, but I'm still not fully convinced.

[weaverryan]

@javiereguiluz if you have a screenshot, sketch, list of all of the things that would need to be on the download page and you want to share, I'd love to see it. I think we can move some of the things to the installation page. Thinking now, the point is that the Download page and Installation should work together - each pointing to the other, and not duplicating. If I start on the Download page, I might just get the very basics done, then be sent to the Installation page. In theory, the Download page could have nothing, and could just be a link to the Installation chapter. The disadvantage is that since the Download page is a custom page (not just a rendered RST), we can add special, magical things there :). So, let's leverage the flexibility that we have on the Download page, then get people back into the docs.

[javiereguiluz]

I think we can close this meta-issue. Let's review the pending items in the TODO list:

Remove most of the installation chapter in the book ... and link to symfony.com/download

We did the opposite. In symfony.com/download we put the minimum useful instructions to install Symfony without explaining anything. In the book's installation chapter we explain everything a bit and we provide alternative download methods (Composer).

Remove specific installation instructions from the quick tour

Done. See http://symfony.com/doc/current/quick_tour/the_big_picture.html#installing-symfony

Re-read the quick tour

We committed to do that in our last Symfony Docs meeting.

Update Symfony Docs index to make it more friendly for Symfony newcomers

We also committed to do this in our last Docs meeting. This work has already started (although it's not public yet).

[weaverryan]

Thanks Javier - I agree. And the fact that we can close this is really cool :)