Update page_creation.rst to focus just on pages, splitting other info to separate doc #4690
Conversation
Radical proposal symfony#1: focus more specifically on creating pages in this document and put related (but not precisely 'dependent') discussions of directories, bundles and environments in a separate document called Structuring a Symfony App. Radical proposal symfony#2: take a heavy axe to The Book to eliminate every description, explanation and detail that's not at the highest possible altitude. Replace extraneous detail with links to the deeper information elsewhere, e.g. Best Practices. The ideal outcome would be DRYer docs and an easier to read and maintain The Book. Keep in mind that I'm a person with 'fresh eyes' vs one with a clear understanding of all objectives that must be met on this introductory page. I expect the best course is something between what I propose and what is currently there. That said, this revision takes an initial stab, so please feel free to use or ignore as you see fit.
|
👎 |
… app_structure doc
|
this pull request adds the separate doc (and guessed-at related changes to include the new doc into to) |
|
One issue I see with this change is that you now put much focus on how to create and structure bundles. However, we recently decided to move away from that point of view and suggest to only create one bundle (the AppBundle). Since this one (and most of the times only) bundle is already shipped with the Symfony Standard Edition, we shouldn't put too much emphasize on describing how to create new bundles. |
|
@xabbuh great point --I'd actually wanted also to pull the bundle description out and get right to creating pages. I think it probably needs to be acknowledged as the first step, but as you say, how to create a bundle doesn't need to be described here. Great place to add a 'see also' reference. Why don't I take a stab in my fork of the docs and make it available as a pull request? Is there a concise statement somewhere of the purpose of The Book? If it's meant as an onramp for new adopters of Symfony, a bit of work to streamline seems worth the effort. If it's meant as "the reference for any user of the platform," it needs much more bulking up. |
…rther on app_structure.rst
|
@ownsourcing Funny that we have such a note in the best practice section, but not in the book. :) Maybe can just copy over the tip from there (see #4702) to the book. What do you think? |
|
I propose to not do things right now, but first think about the documentation structure. Otherwise, we might end up having done lots of work for nothing. I'll create an issue about the structure this week, as I'm planning to create one for a long time already. The docs has grown very quick and with that, the sections have lost their real "goal" a bit. It's good to think about it and see how we can streamline it again. |
Radical proposal #1: focus more specifically on creating pages in this document and put related (but not precisely 'dependent') discussions of directories, bundles and environments in a separate document called Structuring a Symfony App.
Radical proposal #2: have The Book provide a high-level overview with links to the deeper information elsewhere, e.g. Best Practices. The ideal outcome would be DRYer docs and an easier to read and maintain The Book.
Keep in mind that I'm a person with 'fresh eyes' vs one with a clear understanding of all objectives that must be met on this introductory page. I expect the best course is something between what I propose and what is currently there.
That said, this revision takes an initial stab, so please feel free to use or ignore as you see fit.