Improved docs for installation

[fireproofsocks]

To be blunt:

PEAR's docs suck. I mean, they really, really suck. Composer's docs are slightly better, but they too suck.

Since both of these utilities are vital to getting PHPUnit installed, I would humbly request that PHPUnit's documentation go into great, verbose, intense detail in demonstrating how to install this library. Judging by the thousands of forum posts, blog articles, and frantic pleas for help on StackOverflow, I would guess that such instructions would be welcome by many, many developers.

I have tried to use PHPUnit on three separate occasions, spending hours each time trying to get it installed. But each time I have failed. At the end of the day, I give up and use SimpleTest. Maybe it's not as good as PHPUnit, but I'll never know until I can get it installed. At least I can install SimpleTest. All the work you've done developing this project is worthless unless it can be installed, so please, consider writing some new documentation for this critical area.

[sebastianbergmann]

Just ranting "sucks", too, you know. Patches welcome!

[fireproofsocks]

I would LOVE to submit a patch here. Really I would. But since I can't get the thing installed, I have no idea what to change. Closing this issue does not demonstrate much responsibility in this area, nor does it make invalid the thousands of others who have apparently had trouble with this exact thing. I'm off to use SimpleTest.

[theseer]

Not that it's any of my concern - but how is the following line complicated:

 wget http://pear.phpunit.de/get/phpunit.phar && chmod +x phpunit.phar

And why would it need any more docs? The alternatives are not needed (anymore).

[fireproofsocks]

You're missing the big picture: wget is only the smallest part of this. You need examples of what to do with the phar. A few lines there demonstrating a simple script would make all the difference. The docs jump from wget to function definitions and many of us are left wondering if a few pages got torn out of the manual. Compare PHPUnit's docs with SimpleTest's: http://www.simpletest.org/en/overview.html -- SimpleTest shows exactly what to write and how to run it. And only afterwards do they start documenting the specific testing functions.

For example, here's a script I found from a frustrated user on StackOverflow that should test whether or not PHPUnit is working: http://pastebin.com/h2GJFEBU

Just as with the Composer and PEAR variants, I can't get that to work, and I don't see any beginning to end examples anywhere in your docs, so I'm not sure what to change or what I'm doing wrong.

I would urge you to take the time to provide a few simple examples in full: show which files to download, explain where to put them, and explain how to run them. Explain what the user should expect to see as output. Otherwise many people can not take advantage of this code.

[whatthejeff]

@fireproofsocks, sorry you are having issues installing PHPUnit. Hopefully we can help :)

Just as with the Composer and PEAR variants, I can't get that to work, and I don't see any beginning to end examples anywhere in your docs, so I'm not sure what to change or what I'm doing wrong.

I would urge you to take the time to provide a few simple examples in full: show which files to download, explain where to put them, and explain how to run them. Explain what the user should expect to see as output. Otherwise many people can not take advantage of this code.

To be clear, are you reading the official documentation? Just about every example on that page is a full example.

Let me walk you through example #4.4:

Installation:

wget http://pear.phpunit.de/get/phpunit.phar

Or if you don't have wget, you can use curl:

curl -O http://pear.phpunit.de/get/phpunit.phar

And if you don't have curl, you can simply download http://pear.phpunit.de/get/phpunit.phar in the browser of your choice.

Writing the test:

Copy the code from the example into a file named DataTest.php in the same directory where you've downloaded the PHAR. Now run the following command:

php phpunit.phar DataTest

You should get the output shown in the example. That's it!

Alternative install methods:

Composer:

1. Install composer (instructions can be found on the composer website).

2. Create a file named composer.json in the same directory where you've installed composer. The file should have the following contents:

    {
        "require-dev": {
            "phpunit/phpunit": "3.7.*"
        }
    }

3. Install PHPUnit with the following command:

   php composer.phar install --dev

4. Run your test with the following command:

   vendor/bin/phpunit DataTest

PEAR:

This is actually the install method that's being assumed in most of the documentation.

1. Install PEAR if it's not already installed on your system (instructions can be found on the PEAR website). Please note that you may need to upgrade or reinstall PEAR as the version that ships with some operating systems is extremely old/broken.

2. Install PHPUnit with the following commands (note: you may need to run these commands as root):

   pear config-set auto_discover 1
   pear install pear.phpunit.de/PHPUnit

3. Run your test with the following command:

   phpunit DataTest

---

Hopefully this helps. If you see anything that is listed here but missing from the documentation, please open an issue in the documentation project and I'll be glad to make the appropriate updates.

[fireproofsocks]

Thank you for your response. Yes, I'm referring to the official docs. And no, they do not include full examples -- I'm sorry we have such vastly different perceptions of what constitutes a full example, so let me elaborate: the word phar appears nowhere on that page, so one would have no idea how to execute a test using the downloaded .phar file. The first place I've found that info is in your response above. If you can't copy and paste code following the instructions provided, it's not a full example. E.g. look at this screenshot for one place there was an unexplained jump: http://www.screencast.com/t/IXs5WRqx2INR

The longer I work as a developer, the more I realize that coding and writing docs are two entirely different skill sets.

The docs do not point out what the test file needs to be named or whether its name needs to correlate with the class name. Based on the package's popularity, the flow must make sense to many people, but I know I speak for many other developers when I filed this bug and when I said that it feels like some pages were torn out of the manual: the docs are missing that critical information. I'm not ranting: it's just a fact, so it was disappointing to have it immediately dismissed and closed as such. I've added a bug report to the doc project: https://github.com/sebastianbergmann/phpunit-documentation/issues/101

I would love to see that implemented so as to cut down on the time many of us have wasted trying to figure out how the library works.

[whatthejeff]

And no, they do not include full examples -- I'm sorry we have such vastly different perceptions of what constitutes a full example, so let me elaborate: the word phar appears nowhere on that page, so one would have no idea how to execute a test using the downloaded .phar file. The first place I've found that info is in your response above. If you can't copy and paste code following the instructions provided, it's not a full example.

As I mentioned in my response, the examples assume you are using the PEAR install method.

The PHAR/composer install methods are recent additions and we unfortunately haven't had the time to make the type of adjustments to the documentation that you've suggested in sebastianbergmann/phpunit-documentation#101. Please keep in mind that only a handful of people contribute to these projects in their spare time. If you feel like you could help us improve the documentation, please do. Most of us are programmers, not technical writers.

I'm not ranting: it's just a fact, so it was disappointing to have it immediately dismissed and closed as such.

To avoid this sort of thing in the future, it would help if you were more specific, concise, and constructive when reporting an issue. Please consider that following paragraph:

I have tried to use PHPUnit on three separate occasions, spending hours each time trying to get it installed. But each time I have failed. At the end of the day, I give up and use SimpleTest. Maybe it's not as good as PHPUnit, but I'll never know until I can get it installed. At least I can install SimpleTest. All the work you've done developing this project is worthless unless it can be installed, so please, consider writing some new documentation for this critical area.

How is this helpful or relavant? I understand your frustration, but what is your exact issue? We use GitHub to track issues, not to gather feedback. If you have an issue, just tell us the issue and, if you have the time, suggest/contribute a solution. Please leave out the filler.

Anyway, thanks again for sebastianbergmann/phpunit-documentation#101. Hopefully I can get around to it in the coming weeks.

Cheers :)

[fireproofsocks]

I understand where your'e coming from, but when a package does not include the necessary information to get it working, then comments like the one I first posted are about as constructive as you can expect because you've killed the possibility for anything else -- reporting a clean and well-defined bug/feature is impossible in such a scenario. It sounds to me like those responding were in too deep to see the forest for the trees, and that's regrettably common amongst developers, e.g. an explanation of wget was completely off the mark and asking for a fork/contribution is impossible when one cannot get the code to work. So I stand by my original language: it is 100% relevant, and if comments like that don't help you to re-evaluate the state of your docs, then I don't know what will.

Every single developer has the responsibility to demonstrate how their package is to be used in the simplest possible way (PHAR in this case due to the myriad complications involved in using Composer or PEAR). That is not too much to ask -- that's the absolute minimum. Without that info, any code becomes a burden because people spend a lot of time debugging trying to make it work. In such a case, it would be better to keep the code private until it has those minimal instructions.

[whatthejeff]

I understand where your'e coming from, but when a package does not include the necessary information to get it working, then comments like the one I first posted are about as constructive as you can expect because you've killed the possibility for anything else -- reporting a clean and well-defined bug/feature is impossible in such a scenario.

The following would be much more helpful:

The documentation says [...]
I did [...]
But got the following unexpected result [...]

The rest is entirely unnecessary and, frankly, exhausting.

[sebastianbergmann]

The documentation needs little to no modification with regard to PHAR. You download the PHAR, make it executable, and put it somewhere on your $PATH as phpunit. Sorry to say this but I assume that every developer should be able to figure this out in seconds rather than hours or days.