PHP 2024 Documentation Roadmap

[Girgias]

These are ideas that we want to achieve as part of @ThePHPF in 2024:

• Constant linking (Add links to constants phd#102, Add links to namespaced non-class constants phd#111
• Improve call-out to contribute to the docs to be more like MDN which has it at the bottom of the page instead of hidden in the top right (Move contribution links to the bottom of the documentation pages web-php#973)
• Rewrite the "Edited-by" section of the documentation (Add authors and editors from front page to list #3467 and Remove frontpage authors and editors #3468)
• Allow executing examples via 3v4l.org (in collaboration with @SjonHortensius) (Interactive code examples on php.net #3259)
• Investigate adding a "Last Edited" time for individual documentation pages (Add last modification info and contributor list web-php#977)
• Triage user notes (Script to remove outdated and negatively voted notes is now live)
• Implement a support policy for what PHP versions the documentation covers and for how long (Add documentation about which PHP versions are documented #3700)

[SjonHortensius]

Making examples executable would ideally be done by storing the correct script link somewhere. Alternatively a new POST could be done to the correct endpoint containing the full example code - 3v4l will then forward the user to the correct script. I'd be happy to help with supporting the implementation from the 3v4l side

[Girgias]

I think there will need to be some changes in PhD to tie the example content to the output box if it exists, we might also need to limit it to parts of the documentation that does not refer to PECL extensions, as I don't think those are on 3v4l?

[kamil-tekiela]

Is there any plan to split these points into separate issues with better guidance to contributors on what needs to be done? Or is this just an announcement of what kind of work is already being carried out?

[Girgias]

We can split them up into separate issues, the constant linking one is more or less "done" as there has been good progress on this. User notes is something where one needs access to the underlying database so difficult to contribute.

The rest could be their own issues

[pronskiy]

Folks, I've created a #3259 to continue "Allow executing examples via 3v4l.org" implementation discussion.

[kocsismate]

@Girgias What does "Constant linking" exactly mean? Is it that the constants which are documented somewhere else than "predefined constant" pages should be moved to one of these pages and they should be linked wherever they are referenced from? Is documenting the rest of the missing constants/functions/methods too big of a project?

[Girgias]

@Girgias What does "Constant linking" exactly mean? Is it that the constants which are documented somewhere else than "predefined constant" pages should be moved to one of these pages and they should be linked wherever they are referenced from? Is documenting the rest of the missing constants/functions/methods too big of a project?

It's just to have <constant> tags create a link to the constant definition, similarly to how <function> does this for functions. It might require moving constants to the more standard pages, but not necessarilly.

[haszi]

* [ ]  Rewrite the "Edited-by" section of the documentation

Do #3467 and #3468 address this in part or whole?

[haszi]

* [ ]  Implement a support policy for what PHP versions the documentation covers and for how long

This item is addressed by the following PR: #3700

[Girgias]

I updated the text.

[DanielRuf]

Are there plans to add some "edit this page on GitHub"? Because it's a bit hard to find the documentation repo and correct file from the original documentation links.

[Girgias]

Are there plans to add some "edit this page on GitHub"? Because it's a bit hard to find the documentation repo and correct file from the original documentation links.

This is already the case, so I would like to know in what way it is hard?
Note that translations may not have the page translated and so use the English version as a backup, but I don't know if the callout links properly to doc-en. Maybe @haszi knows.

[DanielRuf]

My bad, I was looking at the wrong page @Girgias.

Regarding "hard", the other translations are missing some guidance (to be precise: a readme file) and do not link to the repo for the english / original version:

• https://github.com/php/doc-de/
• https://github.com/php/doc-fr/
• https://github.com/php/doc-en/

And some repos have a different readme file, which is a bit inconsistent.

I think it would be at least helpful to link to the original version / repo in the description:

Repo descriptions support links:

[haszi]

...but I don't know if the callout links properly to doc-en. Maybe @haszi knows.

I just checked and it doesn't.

[Girgias]

Regarding "hard", the other translations are missing some guidance (to be precise: a readme file) and do not link to the repo for the english / original version:

* https://github.com/php/doc-de/

* https://github.com/php/doc-fr/

* https://github.com/php/doc-en/

And some repos have a different readme file, which is a bit inconsistent.

Each translation operates independently, I'm only involved in doc-fr (and even then less so nowadays) and I wrote the README to deal with specificities of it and have a tutorial in a more convenient location than doc.php.net.

So in that case, you need to open an issue on the relevant repo.

[jimwins]

Each translation operates independently, I'm only involved in doc-fr (and even then less so nowadays) and I wrote the README to deal with specificities of it and have a tutorial in a more convenient location than doc.php.net.

So in that case, you need to open an issue on the relevant repo.

Somewhat related to that, I prototyped a version of the Makefile/Docker setup for doing local builds that works in the translations just like the one in doc-en. Like that one, it will use adjacent doc-base, en, and phd repositories if they are available, otherwise it builds them into the Docker image.

php/doc-fr#1534