Re-introduced Validator component usage

[mickaelandrieu]

Hi, I just saw use of Validator component have been removed, probably a mistake (the initial pull request have changed so many times ^^).

This re-introduce the creation of a Validator instance, useful when you use it without use the full edition framework :)

Also, regarding the initial (second in fact) pull request (https://github.com/symfony/symfony-docs/pull/5661/files) why Caching and Resources loading sections have been removed ?

Mickaël

[mickaelandrieu]

Also I notice @wouterj said:

We decided that component users are smart enough to transform framework-usage into component-usage.

This is a non sense, a complete non sense to not document what FrameworkBundle hide to you. Components documentation is about ... "components".

It's not about be "smart", it's about document a library correctly :/

Regarding the published Validator documentation, we have lost a lot of (useful) informations.

[wouterj]

This is a non sense, a complete non sense to not document what FrameworkBundle hide to you. Components documentation is about ... "components".

I think you misunderstood me. Please also quote the first item:

Only document [...] standalone specific things in the components docs.

What we mean is that if we document this in the guides:

$this->get('validator')->validate(...);

The component user is able to transform this into:

// ... initializing the validator (which is still explained in the Validator component docs) $validator->validate(...);

Currently, we most often duplicated the usage documentation in the guides and components, because we considered component users to be not smart enough to make this small transformation. We decided that they are smart enough and that we don't need this duplication.

Still, component usage specific things (initializing and configuring the Validator instance) should be documented in the components docs.

[mickaelandrieu]

initializing the validator (which is still explained in the Validator component docs)

this is the point, and why I open this pull request: we have removed the information about how to create a simple Validator instance :)

Maybe, the removing is unintentional but regarding the comments adressed to the Workflow component docs, I think my concerns are legitimate.

I will always be in favor of removing duplicates, and to put the less efforts to the documentation teams, the red line (for me, very personal point of view) is to document:

• components: high quality standalone libraries that can be used everywhere
• full stack framework: document the integration of components, cookbooks, main principles

Can you tell me what is the philosophy behind the new structure of Symfony documentation ?

[wouterj]

Wow, I just realized you're confused about the new structure. This may result in you thinking we removed all components usage:

• The Guides (the articles and directories in the root) explain framework & general usage (general means usage that's shared between framework and component usage)
• The components directory contains all component introductions (installation) and all component-specific usage details (e.g. how to build a Validation instance)

The information you've added here can be found at http://symfony.com/doc/current/components/validator#retrieving-a-validator-instance

---

Our philosophy is almost equal to the red line you just described. Except that we consider the "framework users" to be the least smart (before someone starts using the Validator or Security components standalone, they probably have more knowledge about PHP and libs then someone just started with Symfony).

To compare:

Section	Your red line	The current philosophy
Guides	integration of components	usage & framework specifics
Components	usage and setup	setup & reference guides for usage

---

Obviously, you're a pretty seasoned documentation user, so if you're already confused, beginners may be even more confused. Can you maybe give some insights in how we can avoid this confusion in the future? (i.e. why did you think the guides explain components set-up?)

---

As this PR turns out not to be correct, I'm going to close it. I hope you understand this :) Closing doesn't mean discussion is ended, so please comment if you have time. (and remember, we can always reopen).

Thanks for your feedback!

[ogizanagi]

@wouterj : There are two related things which are confusing IMO:

• Going on the Validator component documentation page, the "Guides" menu is expanded instead of the "Components" one.
• Going on the Validation guide page, the menu shows we are in the "Guide" section, but we can also see from the breadcrumb that we are in the "The Components > The Validator Component" one.

Mixing the references guides for usage & usage in the framework in the same place (the component doc) is kind of disturbing while navigating on the new documentation, and moreover the left menu keeps misleading the user. 😕

[wouterj]

Going on the Validator component documentation page, the "Guides" menu is expanded instead of the "Components" one.

It's because the Components menu can't be expanded (so it'll expand the default section, which is the guides). But indeed, maybe we should make the components menu expandable as well.

Going on the Validation guide page, the menu shows we are in the "Guide" section, but we can also see from the breadcrumb that we are in the "The Components > The Validator Component " one.

The breadcrumb is indeed incorrect here. It's probably because we're driving Sphinx insane with the toctree usage in the docs (/cc @weaverryan). We probably have to revisit what we're doing with toctrees.

---

For framework users, we want you to never visit the components docs. Most components are not yet updated with this philosophy, but this is at least our main goal. Would this solve your issues?

Thanks as well for your feedback btw, it's highly appreciated!

[ogizanagi]

👍 Fixing those two issues would probably answer most of my concerns regarding the new structure. The philosophy behind is great :)

Thanks.

[mickaelandrieu]

@ogizanagi thanks to have sum up my misunderstanding 👍
@wouterj thanks too, perfectly fine to me, regarding the confusing issue on breadcrumb (also the search engine redirect me to the "Symfony integration of the component" instead of the component itself).

How about change Home > Documentation > The Components > Foo by
Home > Documentation > Framework > Components integration > Foo.

So, for instance:

• Framework docs : Home > Documentation > Framework > Validation
• Components docs: Home > Documentation > Components > Validator

What do you think ?

why did you think the guides explain components set-up?

I didn't think that.

Exploring the hierachy, I have one more idea: how about reword the Guides entries ?

For instance: Guides > Validation => Guides > How to validate your data and re-organize it like the Components section.

Again, thank you for explanations and for the huge work: I may yell sometimes, but this is because I care and I love Symfony ! :)

Mickaël