The documentation and tools for building the PHP documentation are a little scattered at the moment, and I think it would be good to pull them together into one place. The instructions are scattered between doc-en/README.md, doc-base/README.md, docs-base/CONTRIBUTING_DOCS.md and on http://doc.php.net. Not all of the translations have a README.md, and just from looking at those that do, they may not necessarily reflect a standard/current practice for building the docs.
What I’d like to do is pull everything together in the doc-base repository in a docs directory, and we can update doc.php.net to use those files instead of what currently lives in the tutorial directory in web-docs. Each language repository will then get a README.md pointing to those instructions (and language-specific notes can be added as necessary).
This puts the documentation about building the documentation into repos that the docs team has responsibility for, and leaves the web side of it to a repo under the web team’s responsibility.
Any objections or other thoughts on cleaning this up?
The documentation and tools for building the PHP documentation are a little scattered at the moment, and I think it would be good to pull them together into one place. The instructions are scattered between `doc-en/README.md`, `doc-base/README.md`, `docs-base/CONTRIBUTING_DOCS.md` and on http://doc.php.net. Not all of the translations have a `README.md`, and just from looking at those that do, they may not necessarily reflect a standard/current practice for building the docs.
What I'd like to do is pull everything together in the `doc-base` repository in a `docs` directory, and we can update doc.php.net to use those files instead of what currently lives in the tutorial directory in `web-docs`. Each language repository will then get a README.md pointing to those instructions (and language-specific notes can be added as necessary).
This puts the documentation about building the documentation into repos that the docs team has responsibility for, and leaves the web side of it to a repo under the web team's responsibility.
Any objections or other thoughts on cleaning this up?
Here's a first draft of what pulling all of the docs into the `doc-base` repo could look like:
The documentation and tools for building the PHP documentation are a little scattered at the moment, and I think it would be good to pull them together into one place. The instructions are scattered between `doc-en/README.md`, `doc-base/README.md`, `docs-base/CONTRIBUTING_DOCS.md` and on http://doc.php.net. Not all of the translations have a `README.md`, and just from looking at those that do, they may not necessarily reflect a standard/current practice for building the docs.
What I'd like to do is pull everything together in the `doc-base` repository in a `docs` directory, and we can update doc.php.net to use those files instead of what currently lives in the tutorial directory in `web-docs`. Each language repository will then get a README.md pointing to those instructions (and language-specific notes can be added as necessary).
This puts the documentation about building the documentation into repos that the docs team has responsibility for, and leaves the web side of it to a repo under the web team's responsibility.
Any objections or other thoughts on cleaning this up?
No objections from me; on the contrary, I welcome this change (partly
because doc.php.net still hasn't switched to HTTPS).