Skip to content
This repository has been archived by the owner. It is now read-only.

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

Closed
sebastianbergmann opened this Issue Oct 14, 2017 · 10 comments

Comments

Projects
None yet
5 participants
@sebastianbergmann
Copy link
Owner

sebastianbergmann commented Oct 14, 2017

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

This comment has been minimized.

Copy link
Owner Author

sebastianbergmann commented Oct 14, 2017

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

This comment has been minimized.

Copy link
Owner Author

sebastianbergmann commented Oct 14, 2017

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

This comment has been minimized.

Copy link
Owner Author

sebastianbergmann commented Oct 14, 2017

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

@WynnChen

This comment has been minimized.

Copy link
Collaborator

WynnChen commented Oct 16, 2017

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

This comment has been minimized.

Copy link
Owner Author

sebastianbergmann commented Oct 16, 2017

@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

This comment has been minimized.

Copy link

nelson6e65 commented Oct 19, 2017

That's nice! 😃

@gbprod

This comment has been minimized.

Copy link
Contributor

gbprod commented Nov 24, 2017

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

This comment has been minimized.

Copy link
Contributor

keradus commented Jan 4, 2018

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

This comment has been minimized.

Copy link
Collaborator

WynnChen commented Jan 5, 2018

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.

sebastianheuer added a commit to sebastianbergmann/phpunit-documentation-english that referenced this issue Jan 26, 2018

Migrate from DocBook XML to ReStructuredText
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.

sebastianheuer added a commit to sebastianbergmann/phpunit-documentation-french that referenced this issue Jan 26, 2018

Migrate from DocBook XML to ReStructuredText
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.

sebastianheuer added a commit to sebastianbergmann/phpunit-documentation-brazilian-portuguese that referenced this issue Jan 26, 2018

Migrate from DocBook XML to ReStructuredText
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.

sebastianheuer added a commit to sebastianbergmann/phpunit-documentation-chinese that referenced this issue Jan 26, 2018

Migrate from DocBook XML to ReStructuredText
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.

This was referenced Jan 26, 2018

@sebastianbergmann

This comment has been minimized.

Copy link
Owner Author

sebastianbergmann commented Jan 26, 2018

Thanks to everyone involved!

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.