(Hopefully) Everything that is wrong with PHPUnit's documentation

[sebastianbergmann]

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.

[sebastianbergmann]

Ideas for improving PHPUnit's documentation:

• Use ReStructuredText as markup instead of DocBook XML
• Use Sphinx to render the ReStructuredText markup
• Actually let Read the docs render the ReStructuredText markup and host the generated files
• Use branches instead of directories for different versions of PHPUnit documented
• Use separate repositories for translations of the documentation (keep this repository for English, create new repositories for actively maintained translations such as Japanese)
• The translation maintainers should have full control/ownership over their translation's repository
• Translations can be linked to the English original on "Read the docs"
• Translations can be linked to from PHPUnit's website

[sebastianbergmann]

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.

[sebastianbergmann]

@m-takagi @WynnChen What do you think about this?

[WynnChen]

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.).
I have no problem about Using ReStructuredText. but moving translation to separate repositoriyes and using Read the docs for rendering and hosting may increase the difficulty of participation. In the present working mode, If I (or other translators for other languages) become inactive for sorme reason, other people can relatively easily participate and take over our work.

[sebastianbergmann]

@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.

[nelson6e65]

That's nice! 😃

[gbprod]

I can work on the french translation.
Can I start to work on this new version or should I wait you've finished to migrate ?
Can I help to finish this work ? How ?

[keradus]

Just a weird question here about little part of discussion here.
While I see the value of having translated documentation, I must admit that maintenance of it is hell, and they are gonna always be outdated or they will slow down the process.
Is it worth to have them? In terms, like most of the devs simply have to understand English, even if they are not fluent at it, they still understands documentation.

[WynnChen]

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.
Even though translation documentation may be outdated and with some differences in detail, if there is no significant change in the core concepts，new users can still get started easily and quickly and master the basic concepts. Then, when necessary, they can consult the latest English documentation for specific details.