(Hopefully) Everything that is wrong with PHPUnit's documentation #471
Comments
|
Ideas for improving PHPUnit's documentation:
|
|
At the PHPUnit code sprints in Hamburg in April 2017 and in Düsseldorf in October 2017, @belanur, @starikovm, @trueromio, and others have worked on converting the existing DocBook XML sources to ReStructuredText as well as the Sphix-based rendering. They also researched the services offered by "Read the docs". The current state of their work can be found in https://github.com/sebastianbergmann/phpunit-documentation-new. |
|
My focus is on the translation itself and the convenience of participation, and this is the reason why I was participating in this project rather than starting a separate document website/project (And there were already several). The ideal situation is that I can only focus on content translation, without having to consider other work (such as generating documents,hosting pages, etc.). |
|
@WynnChen Thank you for your feedback. The separate repositories for translations could still be "owned" by me in order to prevent the problem you describe. |
|
That's nice! 😃 |
|
I can work on the french translation. |
|
Just a weird question here about little part of discussion here. |
|
High-quality translation documentation is valuable, especially when starting to learn a new technology，even if they‘re somewhat outdated. At this stage, the new technology itself has so much things to learn and to understand, reading in foreign language can greatly increase the slope of the learning curve and can result in the loss of a large number of potential users. |
As discussed in sebastianbergmann/phpunit-documentation#471. In order to make contributing to the PHPUnit Documentation easier, the existing DocBook XML files for the English PHPUnit 7.0 documentation have been converted to ReStructuredText files. This not only makes writing the documentation easier, but it also allows hosting it on readthedocs.org, which offers a very straightforward way of handling translations. Translations of the English version can now be kept in separate repositories, allowing the translators to maintain them themselves.
As discussed in sebastianbergmann/phpunit-documentation#471. In order to make contributing to the PHPUnit Documentation easier, the existing DocBook XML files for the English PHPUnit 7.0 documentation have been converted to ReStructuredText files. This not only makes writing the documentation easier, but it also allows hosting it on readthedocs.org, which offers a very straightforward way of handling translations. Translations of the English version can now be kept in separate repositories, allowing the translators to maintain them themselves.
As discussed in sebastianbergmann/phpunit-documentation#471. In order to make contributing to the PHPUnit Documentation easier, the existing DocBook XML files for the Brazilian Portuguese PHPUnit 7.0 documentation have been converted to ReStructuredText files. This not only makes writing the documentation easier, but it also allows hosting it on readthedocs.org, which offers a very straightforward way of handling translations. Translations of the English version can now be kept in separate repositories, allowing the translators to maintain them themselves.
As discussed in sebastianbergmann/phpunit-documentation#471. In order to make contributing to the PHPUnit Documentation easier, the existing DocBook XML files for the English PHPUnit 7.0 documentation have been converted to ReStructuredText files. This not only makes writing the documentation easier, but it also allows hosting it on readthedocs.org, which offers a very straightforward way of handling translations. Translations of the English version can now be kept in separate repositories, allowing the translators to maintain them themselves.
|
Thanks to everyone involved! |
Although people keep telling me that they think that PHPUnit's documentation is good, I do not think that PHPUnit's documentation is as good as it should be. This starts with the fact that not all features are documented. Most importantly, though, at least in my opinion, the functionality that is documented is not documented well in all cases. I think that this is due to the fact that the same person implemented the functionality and then documented it. I should not be writing PHPUnit's documentation. Not because I am lazy and do not want to do the work. But because when I document a feature that I implemented then I am prone to leave out important details. This is likely a long-term issue that is outside the scope of this ticket.
Over the years, quite a few people complained about the antiquated process and toolchain used for PHPUnit's documentation. These issues must be addressed to make it easier for new people to contribute to the documentation.
When I started to work on PHPUnit's documentation the version control system was CVS. Neither CVS nor Subversion, the system I used afterwards, was any good at handling branches. That is the reason why this repository currently has one directory per version of PHPUnit documented instead of using one branch per PHPUnit version. Not having branches makes it painful to sync changes made in one version of the documentation to other versions.
When I started to work on PHPUnit's documentation I decided to use DocBook XML as the markup language and a toolchain based on DocBook XSLT to generate HTML output, for instance. This choice made a lot of sense, at least to me, back then. After all, that is what the PHP Project uses for the documentation of PHP. It was also something that I was familiar with. I do not think that this approach is appropriate anymore.
The text was updated successfully, but these errors were encountered: