[Documentation] Rewording, improving structure

[ThomasLandauer]

Page: https://www.doctrine-project.org/projects/doctrine-orm/en/current/cookbook/dql-user-defined-functions.html

[ThomasLandauer]

If you merge this, I'll continue with the lower half of the page ;-)

[greg0ire]

@derrabus @SenseException @mpdude this is a first. What's your opinion on where a documentation improvement should go? Since it does not threaten the stability and is not bound to a release (as in, its publication does not depend on a milestone being closed), I'd say either 2.18.x or 3.0.x is fine. Leaning more towards 3.0.x so as to alleviate the maintenance burden.

Let me know what you think and I will update #11208

[ThomasLandauer]

I think it's a bit like the Diataxis framework if you equate Cookbook articles to how-to's

I'm answering down here, so it stays visible after the above conversation is closed as "resolved".

Yeah, I've seen it at https://documentation.divio.com/
But I've never seen it used in practice anywhere, so I doubt it really works out. As I understand it, an example for an how-to guide in Doctrine would be "How to create a webshop".
Symfony had a cookbook, but they moved away from it (probably for a reason - although I couldn't find any discussion about it).

In Doctrine, take a look at these 3 pages:

• Pagination: https://www.doctrine-project.org/projects/doctrine-orm/en/current/tutorials/pagination.html#pagination
• Improving Performance: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/improving-performance.html
• User Defined Funcitons: https://www.doctrine-project.org/projects/doctrine-orm/en/current/cookbook/dql-user-defined-functions.html

Each explains a single topic, so I can't see any reason why one is a tutorial, the other a reference, and the third in the cookbook.
(Just noticing that Pagination is even listed twice in the left navigation bar)

So I think that flattening this structure down to just one list of articles would be a step forward.

[greg0ire]

As I understand it, an example for an how-to guide in Doctrine would be "How to create a webshop".

"How to create a webshop" sounds more like a tutorial to me, because if you write such a documentation article, you are going to have to make a lot of choices that might clash with the reader's idea of a webshop. A good example for a how-to guide would IMO be "how to upgrade from SERIAL to IDENTITY_GENERATED_ALWAYS". It's a list of steps for a user who isn't studying, but getting something out of the way.

Symfony had a cookbook, but they moved away from it (probably for a reason - although I couldn't find any discussion about it).

Symfony seems to find at least "reference" useful: https://symfony.com/doc/current/reference/index.html
As for "tutorials" they even have a separate website with them and just them: https://symfonycasts.com/

Each explains a single topic, so I can't see any reason why one is a tutorial, the other a reference, and the third in the cookbook.

I first heard about divio/diataxis a few years ago, so I'm not sure at all that the people who wrote the docs were following it at all or doing things instinctively.

[derrabus]

What's your opinion on where a documentation improvement should go? Since it does not threaten the stability and is not bound to a release (as in, its publication does not depend on a milestone being closed), I'd say either 2.18.x or 3.0.x is fine.

Yes. Usually, the lowest supported branch should be fine, if the feature that is documented exists there.

[ThomasLandauer]

So is this OK now in 3.0?