Re: [PHP-DEV] Moving `php-src/docs` forward

Hi Nick

Thanks for bringing this up on the list.

Just to state my thoughts officially:

On 20.08.26 23:44, Nick Sdot wrote:
> *Why Markdown:*
>
> - not yet another syntax to deal with; we all write Markdown
reST is pretty popular, so not exactly something esoteric. Sure, I would 
also guess that Markdown is more known, but reST is very hard to "learn" 
either.
> - renderable by default everywhere; including GitHub and IDEs

I don't think this holds.

Before: 
https://github.com/php/php-src/blob/master/docs/source/core/data-structures/reference-counting.rst
After: 
https://github.com/NickSdot/php__php-src/blob/6730bde4ee9ddfe618213441f83af70d49dc347f/docs/source/core/data-structures/reference-counting.rst

The problem here being that this isn't pure reST or Markdown, but MyST. 
I'd guess the same goes for IDEs. Switching the names to .md might look 
better for a good chunk of the file, but then the reST-like parts won't 
render well anymore.

> Please allow me this... If we actually want to move things forward, it 
> would be nice if we would not over-complicate and over-think 
> everything. Otherwise, things just stagnate and (almost) nothing 
> happens as we see with this started but never finished initiative.
I don't think "let's not overcomplicate" should be an argument for 
"let's not question changes". Asking for good reasons for the switching 
from one stack to another seems reasonable.
> So to boil it down, these are internal docs, almost in the same "demo" 
> state as when they were introduced, not important C code. They were 
> introduced 2.5 years ago, yet they still have a big "work in progress" 
> banner, a bunch of todo's inline, and links to 404's (also meant as 
> todo's) in it. Plus, the overall activity to improve was rather 
> moderate. The only actual activity was in `release-process.md` -- 
> which is already Markdown, and not touched by my PRs at all.

None of this is wrong, but I don't think the docs have stalled because 
the syntax is too hard. Rather, more time should be designated to them. 
It's just hard in today's climate, e.g. LLM security reports have taken 
over a large chunk of our time, and even before that issues and user 
docs seem more pressing.

The auto-formatter was also removed in your PR (there might not be one 
for MyST?), I think that's worth mentioning.

Ilija