Revisiting the doc structure

[wouterj]

We have "tested" the core structure in the past year(s) and I think we are at the point where we've learned that it doesn't work as well as planned.

There are some main problems:

1. There is a lot of duplication about the main topics. For instance, routing is explained in the quick tour, the book, the bundles and the components.
2. The book has never been a big success
3. The docs try to explain the CMF as a whole, while we are advocating the CMF a seperate parts (which is, imo, a very good thing)
4. A sub section (the "Create a new project using the CMF" tutorial) is more popular than the main section (the book)
5. Users get a disoriented feeling when reading the bundles docs, since part of it is in the Book, part of it in the Bundles and yet another part in the Reference.

I propose to group things about the same topic more together, keeping the tutorial as the article that covers the CMF as a whole. This means:

• Removing the Book
• Removing part of the Cookbook (bundle related stuff)
• Merging the Reference into the Bundle documentation
• Moving the tutorial to a main section "The Tutorial", which replaces the Book.

I would really like to hear your opinions, thoughts and ideas on the issues with the current docs and how we can solve this.

This issue is, of course, part of the DX initiative.

/cc @dbu @dantleech @lsmith77

[dbu]

i agree with your proposals.

• the split between reference and bundle doc feels artificial and is only confusing. we would still keep the reference a single section in each bundle chapter, right? in general we should have each bundle doc follow the most similar pattern possible so that i know where to find thing. we might provide one linklist somewhere to all configuration reference sections for easy lookup.
• removing the book and integrating it into each bundle / the tutorial seems the right thing.

About the cookbook, i am less clear what you mean. i don't see any bundle specific things.

i think the repetition of things in the quick tour and tutorials can not be avoided, its the nature of doc that goes in iterations from overview to details. with bundle vs component in the routing, the problem is that we need a doc that does not assume symfony and bundles for the component. but the separation and interlinking between bundle and component doc certainly has room for improvement.

[dantleech]

Sounds interesting.. so would the tutorial be the current A > B approach taken in the "Creaing a CMS" tutorial? If we are to cover everything it could have optional sections and alternative paths to get to the destination (i.e. to have a working CMS).

Also would be cool to implement that testing thing for the docs, i.e. to have travis run through all the instructions and actually execute them - @wouterj are you still developing something like that?

[dbu]

with https://github.com/dbu/conference-tutorial i follow a different order, starting with simple cms and only after a while digging into the topic of separate routing and menu. maybe this would be a good approach for this tutorial too. simple cms is the fastest to get something running and is enough in many cases, notably in single language setup. we could do

1. create project
2. using simplecms, consume menu and routing things without any details and advanced things.
3. customizing a simplecms document
4. admin (with alternates if slinp is ready for prime-time already)
5. going deeper into routing
6. going deeper into menu
   (7. eventually we should explain about media in the tutorial. and about seo)

[wouterj]

@wouterj are you still developing something like that?

I'm currently still working on a PHP port of concordion, which should be able to do something like that.

---

About the tutorial implementation, I'm not sure. I've always learned from Ryan to begin with the most minimal you can get and they slowly show the "shortcut methods". So from that point, I prefer @dantleech's step by step approach. On the other hand, many people are exicted about @dbu's workshops...

[dbu]

yeah, i totally see the dilemma and am not saying my approach is the only right thing. the question is whether to quickly have something usable that people who do not need more can even drop out of the tutorial at that point, or have an educational thing that cleanly builds on top of the basics.

with routing auto, dans order can work as well i guess, because there is less nitty-gritty details to explain. (btw, i wonder if we should have the RoutingAuto logic for creating the ids of simple cms documents as well? might not play well with the menu though.)

[dantleech]

I have done a brain dump: https://github.com/symfony-cmf/symfony-cmf/wiki/A-Big-Tutorial

[dbu]

good idea. the non-default paths are basically what we are still missing. so we would build it along the main path, and add the alternative parts in when there is enough ready and somebody gets down to write things.

[dantleech]

btw. I made a sphinx extension last weekend which will eventually generate Behat fixture files:

https://github.com/dantleech/sphinx-behat

So the idea would be that sphinx would a .feature file for each document, and then travis would run and behat would complete the tutorial. Will hopefully have a closer look this weekend.

[benglass]

I agree that people find the docs confusing and that the divisions between
the core stuff and the bundles feels artificial. I have experienced that
cognitive disconnect about being confused about where to add documentation
as a contributor (whether its in bundles or core or the book).

I think there is still some confusion out there as to what the cmf is sadly
that results in frustration for potential users who dont understand the
benefits

http://www.reddit.com/r/PHP/comments/2bb79c/pagekit_a_new_modern_cms_built_with_symfony/

On Wed, Aug 6, 2014 at 4:31 PM, dantleech [email protected] wrote:

btw. I made a sphinx extension last weekend which will eventually generate
Behat fixture files:

https://github.com/dantleech/sphinx-behat

So the idea would be that sphinx would a .feature file for each document,
and then travis would run and behat would complete the tutorial. Will
hopefully have a closer look this weekend.

—
Reply to this email directly or view it on GitHub
#523 (comment)
.

[dbu]

i think we have a conflict of interest between:

• introducing new people to what the cmf can do and show how things work together
• showing a cool tutorial with a "story" that progresses
• explaining how to use each of the bundles stand alone for projects that don't need all the cmf but just some bundle
• have a complete reference of each bundles feature

all those points should not create duplication to make maintenance possible. but just linking back and forth all over the place gets people lost. and just the amount of information to chose (do i need the tutorial or the individual bundle docs?) can confuse people.

[wouterj]

Only the book now needs to be removed. That needs to be done more carefully, since we shouldn't loose any information and some articles (like book/database_layer) are better than the current documentation.

Fyi, I've also updated to redirection map to not get 404 URLs on the current URLs: symfony/symfony-docs@df640b2

[dbu]

do we still do something here or leave things as they are now?

[dbu]

@wouterj ok if we close this and continue discussion in #696 ?

[dbu]

book removed in #835