Last weekend while I was out at my cabin, Ryan Janssen was trying to install PamelaWare for WordPress. Generally I wouldn’t be too concerned, as my project members and I have worked hard to make the install relatively easy.

I try to make myself available as tech support if I know anyone is trying to get the plugin to work, because I want to make sure everyone has a good experience — but in doing so, it turns out that I was masking a critical flaw in both the documentation and the administrative user interface.

For more details, you should read Ryan’s entry, I recommend it – the entry very clearly describes his frustration around not knowing what format of private key, passphrase, and domain name the plugin was expecting, and his eventual success by brute-forcing all of the possible combinations.

Obviously, this isn’t exactly the review I was expecting :) But luckily, I have just finished Henry Petroski’s book “To Engineer is Human; The Role of Failure in Successful Design” (recommended during Brian Cheess & Gunnar Peterson’s AWESOME RSA talk). As such, I have to note that I did not design to obviate failure in this case — but that the failure Ryan experienced can now be learned from and used as a cautionary tale for the future.

As a result of Ryan’s sacrifice of time and his willingness to describe his pain, I’ve updated my documentation to include an SSL Primer and an SSL Certificate FileType Guide, as well as screenshots of what a typical filled-in interface might include. I’ve also added a page explaining how to tell if your environment is set up for PHP version 5 and mcrypt (prerequisites for PamelaWare). I have not yet improved the user interface, but I will. I also think there is more to do, to explain what happens next once you’ve installed and configured the plugin. The great thing is, I’m now focused. And I can always go back to Ryan’s blog if I need to capture that feeling of “WTF do I do now?” :) Many thanks to Ryan for not just walking away, and for writing it all down.