Searching through the AWS SDK for PHP documentation • Flailing Wildly

Although the AWS SDK for PHP is growing as fast as Amazon’s breadth of web services, it should still be easy to find the information that you need in order to develop. This is a goal that I take very seriously.

Back in 2005, I took a job with Stryker Endoscopy as a member of their Internal User Experience team, where our focus was on Usability and User-Centered Design (UCD). (I take no responsibility for how bad their public website is!) I gained some invaluable insight into the usability process and the principles behind UCD that I’ve carried with me over the years as I’ve migrated from UX and Front-End Development toward building Software Development Kits (SDKs) for infrastructure services. The most valuable of these is this:

You can have all of the greatest functionality in the world. But if nobody can use it, what’s the point?

I’m tempted to launch into a tirade against the stunning ignorance of software engineers who think we UX people “make it look pretty.” A Photoshop mockup does not a user experience make. Those same woefully uneducated people don’t understand how much science is involved in producing high-quality user interfaces — nor do they understand that if a person can’t figure out how to use the software, it’s not a problem with the person… it’s a problem with the software. As I’ve shifted toward producing developer-facing software, I’ve always maintained the notion that “developers are people too.” The administration and developer tools of some web applications are a crime against humanity. Of course, that’s what happens when you make the mistake of thinking that corporate stakeholders are your customers instead of Real Human Beings™. [I’m starting to rant. Let me switch gears.]

I ♥ Quality

I believe that documentation is equally — if not more — important as the code itself. It’s a critical part of the user (i.e., developer) experience right up there with API design and SDK design. When I was building CloudFusion (the pre-cursor to the AWS SDK for PHP), I spent quite a bit of time trying to find a high-quality documentation tool that delivered what I believed my users deserved. After searching for a good tool over the course of 2–3 years, I finally broke down and wrote my own tool that produced the kind of high-quality documentation that my users deserve. (That project is called “Vanity”, and is currently incubating).

Making It Better

With the release of the AWS SDK for PHP 1.2.4, we really tried to raise the bar for our documentation. Here are some of the features that we now provide:

Rewrote the in-file documentation blocks to use the more common and better supported PHPDoc format instead of the NaturalDocs format we used previously.
Complete API reference documentation for all methods and classes.
One or more usage examples for nearly every single method.
Usage examples are generated from real PHPT tests, ensuring that the sample code actually works.
A breakdown of all complex parameters so that you can see what all of the possible options are.
The API reference documentation is available in HTML, raw XML, raw JSON and Serialized PHP formats.
Offline documentation can be downloaded as .zip, .gz and .bz2 archives.
Intelligent search along with a class browser.
View the source code of any method in the SDK.
The file that a given method is defined in.
Links out to the GitHub repository.
Complete inheritance chains and interface conformity.
Methods that are related to the one you’re looking at.
Links out to PHP.net, where appropriate.
Instant feedback, as in the ability to point out an error or some other issue directly on a page itself, instead of needing to hunt for a feedback link somewhere else in the site.
The ability to link directly to a search query.

It’s this last feature that I’ve come to talk about today — the ability to easily search the docs from tools you already use.

Searching the AWS SDK for PHP documentation from Google Chrome

For this, we need to tell Chrome to use the following pattern when searching the API reference.

http://docs.amazonwebservices.com/AWSSDKforPHP/latest/?q=%s

Open the Google Chrome preferences panel.
In the Search section, click Manage Search Engines…. This will show the Search Engines panel.
In the Other search engines section, fill out the fields as shown below. The URL in the last field is the one I posted above.
Open a new tab. Typing “aws[space]” will trigger the AWS SDK for PHP search. Search for whichever keywords you’d like. At the time of this writing, classes, methods, properties and constants are supported.
This will open the SDK API reference documentation. Your search terms will be pre-filled in the search field on the left. You can navigate through the documentation from there!

Searching the AWS SDK for PHP documentation from Mozilla Firefox

This process is very similar to Google Chrome. For this, we need to tell Firefox to use the following pattern when searching the API reference.

http://docs.amazonwebservices.com/AWSSDKforPHP/latest/?q=%s

Open the Firefox Bookmarks Manager by choosing Bookmarks > Show All Bookmarks from the menubar. Once that’s open, click the gear icon and create a new bookmark.
Firefox will present a New Bookmark dialog.
Fill out the fields as shown below. The URL in the Location field is the one I posted above. Firefox calls this a Keyword Search.
Open a new tab. Typing “aws[space]” will trigger the AWS SDK for PHP search. Search for whichever keywords you’d like. At the time of this writing, classes, methods, properties and constants are supported.
This will open the SDK API reference documentation. Your search terms will be pre-filled in the search field on the left. You can navigate through the documentation from there!

Searching the AWS SDK for PHP documentation from Alfred

This approach is my personal favorite, but is specific to Alfred, an app launcher for Mac OS X. For this, we need to tell Alfred to use the following pattern when searching the API reference.

http://docs.amazonwebservices.com/AWSSDKforPHP/latest/?q={query}

Alternatively, you can use the following URL to accomplish what we’re going to do here:

alfredapp://customsearch/AWS%20SDK%20for%20PHP/aws/utf8/url=http://docs.amazonwebservices.com/AWSSDKforPHP/latest/?q={query}

Open the Alfred preferences, and choose Custom Searches from the sidebar. Once there, click the plus symbol at the bottom to add a new custom search.
Fill out the fields as shown below. The URL in the Search URL field is the one I posted above. Click Add when you’re done.
Close the preferences, and bring up Alfred! Typing “aws[space]” will trigger the AWS SDK for PHP search. Search for whichever keywords you’d like. At the time of this writing, classes, methods, properties and constants are supported.

The End

I hope that this tutorial helps make your use of the AWS SDK for PHP even easier! Are there some other cool uses for the SDK docs that I might not be aware of? Let me know in the comments!