On 29.05.26 02:15, Jordi Kroon wrote:
Hello,
I've opened an RFC to separate third-party extension documentation
(imagick, redis, mongodb, etc) from the official PHP manual, while
keeping the existing DocBook tooling and infrastructure.
Bundled extensions (pdo, curl, etc) are out of scope and stay in the
official PHP manual.
https://wiki.php.net/rfc/third_party_ext_documentation
Hey Jordi,
thanks for the RFC, I am all for this!
From the RFC:
```
Third-party extension documentation will be hosted in a single monorepo,
mirroring the structure of the existing|doc-en|repository. Each
extension occupies its own subdirectory, and the repository uses the
same DocBook-based tooling as the official manual.
Commit access may be granted to extension maintainers in addition to the
PHP documentation team. Pull requests remain open to anyone, as
with|doc-en|.
```
How about co-locating the documentations in the extension repositories?
Tooling could pull in the documentations from there.
Moving third-party docs to a monorepo sounds like it moves parts of the
maintenance burden and confusion from place A to place B under the same
roof.
The responsibility to manage access still would be with the docs team.
Third party docs still would live in a phpc owned repository.
*Benefits of co-locating:*
- docs fully owned by extension
- no access management burden for docs team
- no bad look for phpc if the monorepo has hundreds of open issues/prs
(if some maintainers don't care)
- maintainers can document as they go; doc changes can land in the same
pr/commit
- maintainers can choose their own workflows, issue templates, etc.
- users can contribute where the extension lives; maintainers directly
handle contributions
- maintainers triage/handle only their own issues/prs in their own repo,
without being overwhelmed by unrelated issues/prs
- no confusion about why third-party docs live in official PHP repos
- archiving/removing docs is as easy as removing/deactivating the
external integration source
I think co-locating would add a lot of value, while still achieving the
goal you propose.
Admittedly, this approach would require slightly more coordination than
your proposal. It, however, would also serve as a great first filter to
evaluate which extensions are still maintained, hence worth documenting
(promoting), and which not. The initial move could be automated with PRs
to the extension repos. I'd argue the extra effort is negligible and the
upsides outweigh it.
Thoughts?
--
Cheers
Nick
