Create a new project using PHPCR-ODM removed?

[dantleech]

There used to be a doc for creating a new project based on the SF standard edition, which now has since been removed

Any reasons why? I found that article pretty handy ..

[dbu]

i moved most of that tutorial in #472 to the bundle documentation of phpcr-odm. there was just too much redundancy between the installation instructions in the bundle doc and the tutorial. when you look at the updated bundle doc, do you think we lost something important in #472?

[dantleech]

I think so.. that was a step by step tutorial to create a new project with phpcr-odm. The DoctirnePHPCRBundle does not cover (nor should it) installing the standard edition, making the necessary modifications to composer.json or adding the recommended parameters to parameters.dist.yml.

The idea of that tutorial was that you start at 1 and when you get to x you have a working project, it is a different type of documentation.

[dbu]

http://symfony.com/doc/master/cmf/bundles/phpcr_odm/introduction.html does mention the composer.json bit. i think its pretty complete in installation instructions actually. and then we have http://symfony.com/doc/master/cmf/cookbook/creating_a_cms/getting-started.html and the standard-edition to start from or cmf-sandbox to look at.

i think too much redundancy in those docs is not only hard to maintain (and thus will become outdated) but also confusing because people can look at too many different things that talk about the same in slightly different ways.

[dantleech]

But the instructions do not tell the user how to create a new project. That article as originally part of the Creating a Basic CMS tutorial.

I think tutorials are more useful than bundle documentations, they are goal based and take the user through a real process. I used that specific article every time I created a new PHPCR / CMF project.

[wouterj]

Well, afaik the only difference between the (now removed) tutorial and the bundle docs are that the bundle docs do not mention the composer create-project symfony/framework-standard-edition command?

I tend to agree with @dbu

[dantleech]

1. How does a user start with the CMF? Where is the entry point? IMO it was that article.
2. The DoctrinePHPCRBundle explains that bundle, not how to create a base project for CMF / PHPCR

Apart from that, the new documentation does not contain the following (don't know how current it is)

• Doesn't show how to remove the ORM
• Doesn't show howto modify parameters.yml.dist to have the phpcr_* parameters

It was originally part of the Creating a Basic CMS tutorial, and the new documentation overlaps with that tutorial.

It was meant as a building block for further tutorials too.

[ElectricMaxxx]

have to agree to @dantleech. I love tte tutorials it's as your (@dbu) tutorial for your workshop.
For guys with less experience it is a nice experience to see stuff working step by step. There might be redundances, but that are on an other level. It isn' t the point to mention every possible setting/installing instruction on several places. It is a point of seeng stuff work and get a happy feeling as in your workshop-tutorial. That one leads me to my first working cmf-system and makes me smile.

[dbu]

we can try to make the "building a cms" tutorial chapters more independant. or not talk about setup phpcr-odm in that tutorial at all and make it separate again. then from the tutorial reference it, like a food cookbook references base operations like making base sauces and such.

[dantleech]

then from the tutorial reference it, like a food cookbook references base operations like making base sauces and such.

This is what we decided to do last time .. that is what that tutorial was...

[dbu]

so i was not careful enough when cleaning things up. but i think what we really should do is:

• each bundle doc should explain how to install that bundle, linking to prerequisites where needed.
• one cookbook article how to add phpcr-odm + cmf to an existing symfony project, without explaining any of the meaning of the bundles and only real minimal configuration.
• the building a cms tutorial should not talk about installing at all, but require to either do the manual install or take the symfony-cmf/standard-edition as starting point.

wdyt?

[dantleech]

each bundle doc should explain how to install that bundle, linking to prerequisites where needed.

yes

one cookbook article how to add phpcr-odm + cmf to an existing symfony project, without explaining any of the meaning of the bundles and only real minimal configuration.

I thought that was what the article did.

the building a cms tutorial should not talk about installing at all, but require to either do the manual install or take the symfony-cmf/standard-edition as starting point.

That tutorial already delegated the installation to that article .. ?

[dbu]

yes, it was more or less the case. but either i was moving too many things and got confused, or there where indeed overlappings, so i felt this was the best way to clean things up. but you convinced me i went the wrong way. just wanted to summarize what we need to do now, so we get it right this time ;-)

[dbu]

i guess the install cookbook entry is basically https://github.com/dbu/conference-tutorial/pull/2/files with some comments, right? and make sure that the building a cms only talks about configuration and otherwise links.

do you want to do it or shall i?

[dantleech]

Well, I prefer the original document (I am biased since I wrote it). It told you efficiently how to create a new project using the PHPCR-ODM - you followed every step and then you had a working project. The tutorial you reference has lots of dependencies - dependencies which I maybe don't want, and I would have to figure out how to remove them.

It was a building block for the "Creating a Basic CMS using ..." tutorial. The beauty of which was that it presented explicit steps which enabled you to start from zero to having a full CMS in 1 hour - it is an entry point into the CMF

So much time went into that tutorial, especially ensuring that every step is covered. I would prefer to put the original document back or removing both the articles until we can decide on a better strategy.

[dantleech]

(because I believe there are outstanding issues with the "Creating a Basic CMS ..." tutorial and hopefully the new RoutingAutoBundle should be out soon .. ish)

[dbu]

but if the tutorial should be only about how to set up phpcr-odm, then the bundle doc should be where this is. if the bundle doc is not good, we should improve it rather than add a separate cookbook entry and have two overlapping documentations about the same thing. i think the differences between the phpcr-odm bundle introduction and https://github.com/symfony-cmf/symfony-cmf-docs/blob/1.0/cookbook/create_new_project_phpcr_odm.rst are quite marginal, and don't see the need for a separate cookbok. if you think we should move some things from the phpcr-odm bundle intro into separate sections to get the intro more concise, i am +1 for that.

[dantleech]

But .. the style is diffent - its step by step - and, crucially, this is about creating a new project -- its also about creating a project in such a way that the rest of the tutorial will work.

This was a "recipe" in the "cookbook" for creating a new project. It may overlap with some of the bundle documentation, but it is presented in a different way - the bundle documentation will never be as instructional as this article, which was practical and timesaving imo :)

[dbu]

i am very afraid of the burden of redundant documentation. but i do see the tutorial use case of course. can you resurect the cookbook (and boil it down to the minimum and reference the bundle doc for explanations where possible)? i am ok to have it back in.

[dantleech]

I think this document naturally be maintained, as it is expected that every step works, and people will do it every time they do the tutorial, so any inaccuracies should be quickly picked up on and I will do an end-to-end test to ensure that the docs work when we go stable.

I have already resurected the tutorial in the new RA documentation (although maybe I havn't commited it yet). I would prefer to wait until 1.2 (or when we release the next version of ODM and RoutingAuto) to put this back, and I guess you don't mind it not being there atm :)

Hopefully the RA bundle should be ready soon (oh yeah .. soon)

[dbu]

👍

[wouterj]

From a user perspective you should never have duplicate documentation. You simply can't keep them in sync. And yeah, 1 in the 100 readers of your docs will fix the inconsistencies, but that means 99 people get confused by it.

That was the problem we got in the core docs, which we try to tackly now. The installation proces was described too mang times: symfony.com/download, quick tour, book, readme They were all quite similiair, but the little differences made new people unsure about what to do.

[dbu]

wouter, according to your opinion, which is the right place to explain how to install? the bundle doc or a cookbook entry? if the bundle is explaining options in detail and such, it indeed does not make for a good fluent reading of how to install.
how do you solve the problem in the symfony doc? i guess needing to jump around too much in the doc is also a usability issue...

[dantleech]

The "Creating a CMS" tutorial is not typical of the type of documentation that exists in Symfony - it is more like the "Jobeet" tutorial. I don't think we can apply the same criteria to it. We could equally remove it from the CMF documentation all-together and host it somewhere else (CMF University :P)

[wouterj]

No matter what type of documentation it is, the fact that it is written on multiple places is still true.

However, I've been thinking about the documentation structure yesterday (had an 9 hour drive back to home) and I think we have to completely revisit it, giving a better place for your tutorial. See #523