[RFC] Separation of Third-Party Extension Documentation

I don't understand what the problem with translations. What is so special about english that it can be lift-and-shifted, but other languages cannot? What specific coordination is required from the translation team?

Translations could be lift-and-shifted the same way English can. The asymmetry is about responsibility after migration, not the migration itself.

A few concrete points:

• Translations track the English version via revision hashes, so they
  depend on the English source. English is canonical; while the other
  languages are downstream of it.
• A majority of translations have less than 50% coverage
  (https://doc.php.net/revcheck.php).
• The whole point of the RFC is to hand documentation responsibility
  to the extension maintainers. That works for English because English
  is the de facto language. It does not work for the other languages.
  We can't reasonably assume an extension maintainer is fluent in
  German, French, Japanese, etc.
• Structurally, carrying translations over would mean one contrib
  repository per language, mirroring the current doc-en / doc-de /
  doc-fr / doc-ja / etc. So the overhead the RFC is trying to
      reduce would be reproduced in the new location.
• It is already difficult to keep a single language in sync with
  extension releases. Asking extension maintainers to keep N languages
  in sync. Languages that the extension maintainer can't read or
  understand. Thus a language the extension maintainer can't verify
  the contents of.

If we want to transfer responsibility, wouldn’t the only
responsible course of action be to not only hand over
the edit history in the canonical language, but also
that of the translated works?

Regarding what you say about the contrib repositories:

They can be one repository per extension, so to be
honest, I can’t really follow that line of reasoning.

Which is perhaps why I feel that the ‘Shift’ in ‘Lift
and Shift’ in the RFC leans too far to the right and
appears misplaced to me.

I’d prefer to see it further to the left, just like the
‘Shift’ in ‘Shift Left’:

Assuming a new iteration is created, and once it passes
CI, the build and source code are handed over (the
‘Shift’ operation in form of one repository), then
deleting the translated books and their history is no
longer required for the handover during ‘Lift’, as a
single Git repository is already sufficient according
to the discussion so far if I'm not mistaken.

So my substantive question remains: is this a handover
of responsibility under which we also want to act
responsible?

In that case, in my opinion, we should do us the favour
and not make too many assumptions about what future
editors will do with the work. Especially if that is
done in the light of technical difficulties, as I'm
confident we're able to handle it, so that we include
the translation and the history in their current form.
We should enable any future readers – rather than
hindered – to act responsibly.

The revision history is important – particularly when it
comes to the documentation and its translation.

We should lead them by the best example only,
not telling them that is is a fruitless effort to
organize their translations (or vice-versa, as you
correctly wrote, only because English is canonical for
the translation, after handing the books over, this can
become entirely different.)

-- hakre

Translated from Englitsch to German back to Englisch
with DeepL.com (free version)

AFAIK, every third party extension includes configuration and
installation instructions that make clear whether the extension is part
of php-src or not; can you point at an example of this confusion in the
real world ?

The role of PECL (or PIE) may not be known for (new) users. Thus having
those kind of extensions in the official documentation gives the false
assumption that these functions or classes as in fact available.

While this distinction is usually documented in the installation section
of each extension, that is often not the first page users arrive at. In
practice, many users land directly on a function or class page from a
search engine, copied snippet, StackOverflow answer, or any other source.

For example, intl is bundled with php-src and still has a dedicated
installation guide in the manual. So the mere existence of installation
instructions is not, by itself, a reliable indicator to users that an
extension is external to php-src. From a reader’s perspective, bundled
and non-bundled extensions can appear structurally identical within the
documentation.

If the third-party extension maintainer went through the effort of
generating documentation in an antiquated awkward format, they might
expect typos not to require their input. However, I don't think any
extension maintainer expects documentation maintainers to track API
changes; they handle that themselves for the most part. It's my
impression this is well understood among active maintainers.

I agree that active maintainers generally understand where
responsibilities lie today. My concern is more about the expectations
created for readers and contributors outside that group.

From the outside, all extensions documented under the official PHP
Documentation appear equally "official". Readers reasonably assume a
similar level of maintenance and review continuity across the manual,
even when that may no longer be true for some third-party extensions.

There are probably sections of the documentation likely contains
sections for genuinely abandoned extensions and we should have a
mechanism to address this.

At the moment, it is difficult to tell whether:

• the extension itself is still actively maintained,
• the documentation reflects current releases,
• or anyone is still reviewing and resolving documentation issues.

As a result, documentation issues can remain open indefinitely without
readers having a clear indication of the maintenance status or
reliability of the documentation they are reading.

This idea as proposed is -1 from me, it seems to create an undue burden
(on top of the format's inherent burden) for third-party maintainers.

The primary issue the RFC tries to address is not maintainer confusion,
but the expectations created for readers by hosting third-party
extension documentation inside the official PHP manual.

By being part of the official PHP documentation, third-party extensions
appear to have the same level of oversight, maintenance, and reliability
as bundled PHP functionality, even when the way they are maintained may
differ significantly in practice.

Separating third-party extension documentation also allows those
projects to evolve documentation independently, without inheriting the
same expectations of maintenance and review as bundled PHP
functionality. This in turn reduces the need to strictly adhere to the
full PHP documentation format and style requirements, making it easier
for extension documentation to be updated and maintained.

From the perspective of extension maintainers, the practical change
would be minimal: documentation would simply live in a separate
repository with relaxed format and style requirements.

--
Regards,

Jordi Kroon

What happens if the RFC fails? Do we just do nothing and let the PHP
manual deteriorate further?

Are there any abandoned extensions that make no sense to keep the
documentation for? Wouldn't it be wiser to prune the docs of these
abandoned extensions and then deal with the remaining per the outcome of
the RFC.

Regardless of whether this RFC passes or not, the documentation team
will continue trying to prune/archive documentation for genuinely
abandoned extensions where appropriate.

That said, it is not always straightforward. As these are third-party
extensions, we do not always have a clear picture of their maintenance
(or usage) status, and a lack of recent updates does not necessarily
mean an extension is no longer functional with current PHP versions.
Extensions could remain stable for years without requiring active changes.

Because of that, determining what should actually be removed or archived
requires careful consideration. This RFC would also help clarify the
boundaries and expectations around maintaining third-party extension
documentation going forward.

--
Regards,

Jordi Kroon