Update: It seems that the facts presented to me in the initial bug report are not correct. I will be revising this article after the facts are settled. For now read the comments.

It all started with a simple bug encountered while trying to get PHP and WCF to play nice. Before you know it I was attempting to compile PHP on windows myself. That’s when I realized how deep the rabbit hole really goes.

These days I program in PHP and .NET for a living. In a past life I was a unix admin for small ISP where most of the internal unix infrastructure was FreeBSD while the managed customers tended to run Redhat.  Due to the unique path of my IT career, I usually don’t have a problem compiling open source software primarily targeted for unix on windows. PHP has proven to be a bit of an exception. However, with a little struggle, I got it to compile.

In this case the crux of the struggle was not a lack of documentation, but documentation outdated to the point of being wrong. This is perhaps the one exception to the rule postulated by Dick Brandon, “Documentation is like sex . . . when it is good, it is very, very good; and when it is bad, it is better than nothing.” Thankfully, Pierre of libgd fame pointed me in the right direction on the mailing list. So being a good netizen, I submitted a bug report so that someone with commit access to the php source repo could straighten the mess out. This was the response I received:

We don’t understand the build requirements or system.

You have to ask the Microsoft guys to update that file.
http://no.php.net/manual/en/install.windows.building.php was one of our
best Windows know-how (not-microsoft-employee) guy shot at documenting
the process, but the feedback he got from Microsoft employees was “this
is crap. its all wrong”.

Sorry, we simply do not know how to do this.

That was a little disheartening. I asked them to mark the readme file as outdated, and I asked them how to contact Microsoft. This was the response I received:

Updated the file to say its outdated.

As for contacting the Microsoft guys, try surfing around on
http://windows.php.net

We have tried multiple times to get these docs updated, with no luck so
far, and like I said; our last attempt was shot down and they wanted
those docs to be reverted.

I’m sorry, you are simply on your own here.

So it seems my only resort is to blog about it and hope someone from Microsoft is in earshot. If you care about PHP on windows, spread the word. Spread this article with twitter, digg, reddit, or just plain old email. If you have the ear of anyone in Microsoft give it a bend. I’ve never attempted blogger activism like this, but I don’t know what else to do. I much prefer to fix problems myself than delegating or inspiring. However, this is one case where I need to “have a little help from my friends.” I don’t even know what Microsoft finds wrong with the proposed updates to the documentation, so submitting updated documentation seems pointless.