Hey everyone,
I started updating, restructuring, and modernising `php-src/docs`, which
also includes migrating the existing Markdown based `php-src/docs-old`
into the book. The first step in my prerequisite series of PRs (please
check the PR desc to see the full scope of all PRs) give the current
docs a Markdown facelift:
https://github.com/php/php-src/pull/23368
*Why Markdown:*
- not yet another syntax to deal with; we all write Markdown
- renderable by default everywhere; including GitHub and IDEs
- less bloated for titles, inline code, prose and such
- we can easily extend it later if we want to
That said, Ilija -- who initially did setup the book 2.5 years ago --
considers the change as "churn" and asked me to better bring it up on
list. I didn't expect this to be a topic fo the list, but here I am. :)**
*My Argument:*
It's a light ~1,100 line, mechanical diff (see first PR). Though, if we
would not do it in the first PR, we would do it vice versa in the later
PR that integrates `php-src/docs-old` into the book -- which has pretty
much the exact same amount of lines. So we will have "churn" in one or
the other direction. These docs are so aged, outdated, incomplete that
there will be *much* more changes over the next weeks and months (see
last PR). Given that, I don't see any reason for holding back because of
"churn". This switch to Markdown reduces lines already by ~100 lines,
just for 17 existing documents. Not to forget, CODING_STANDARDS.md and
CONTRIBUTING.md which have contents that eventually should be integrated
into the book, are also already Markdown.
Where I agree with Ilija is that the reST table syntax is better. The PR
is already updated to use reST for tables -- both can co-exist nicely.
*My Opinion*
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. Ilija did a great job,
but it was merged it with the words:
> some chapters first just to give an idea of the depth and language
that is expected
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.
From my own onboarding experience I know how complicated and confusing
things are; I strongly believe this is not the state these docs should
be in.
*My Ask*
Devs are understandably busy with other things, and no one can or want
to get it done. So here I am, offering myself to help out. Those who saw
my recent contributions might already know that I am interested in
making myself helpful by improving the test suite, CI, and general QA
stuff. I see these docs as a part of it, because A) docs = QA, B) a lot
of test related stuff has to be documented, and C) while I monitor PRs
for test related stuff I often see things pointed out in reviews that
are worth to be documented.
A preview of the "final" state of the prerequisite PR series can be
found here:
https://nicksdot.github.io/docs-restructure-final/
After these prerequisites are merged I can start to cook.
I'd appreciate if I could get everyone's blessing to get this done. 🥷
---
Cheers
Nick
