[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?

[github-actions]

There hasn't been any activity on this pull request in the past 90 days, so it has been marked as stale and it will be closed automatically if no further activity occurs in the next 7 days.
If you want to continue working on it, please leave a comment.

[SenseException]

Meanwhile it should be fitting for 3.3.x

[github-actions]

There hasn't been any activity on this pull request in the past 90 days, so it has been marked as stale and it will be closed automatically if no further activity occurs in the next 7 days.
If you want to continue working on it, please leave a comment.