In a world in which many developers (myself included) use web search as their first avenue of inquiry when they run into a technical problem, it’s important for platform providers to have technical content that is thorough, well-organized, and discoverable from web search engines. (This means that you should apply the principles of search engine optimization to your entire site, not just the marketing bits.)
Way too many technology products expect third party developers to flock to their platforms on the strength of the product alone, without providing any documentation to help them get started. Documentation isn’t an amenity, it’s a requirement.
If your documentation isn’t easily searchable, then 10-70% of current and prospective developers aren’t going to be able to find your documentation when they need it.
Keeping your developer content up to date as your platform evolves is another big challenge. Microsoft does a terrific job of keeping its voluminous body of developer content current while deprecating and removing old content. Not so, unfortunately, with the large number of third party community sites that cover Microsoft technology. In this situation, the third parties’ objectives aren’t in alignment with their users, since (presumably) taking down outdated content decreases the third party sites’ pageviews and clickthroughs.
This came up today because I’m investigating how ASP.NET developers can localize their sites into different international languages. As it happens, the rules pertaining to localization totally changed from ASP.NET 1.1 to ASP.NET 2.0. (Things got much easier in 2.0.) Since I didn’t know much about localization in the 1.x era (Chris Kinsman and I didn’t cover it in our ASP.NET 1.0 book), I started with a web search and immediately ran into a ton of outdated content on .NET localization which wasted several hours and made me semi-cranky.
After many wrong turns, I wound up at the place where most .NET developers begin: the QuickStart Tutorials. The tutorial for localization in ASP.NET 2.0 is terrific and it got me what I needed in a hurry. (All of Microsoft’s .NET QuickStart tutorials are terrific, really — if I had to point out a single thing that helped .NET get adoption since it was introduced in 1999, the QuickStart Tutorials are probably it.)
The point is that even the biggest-brained developers can benefit from simple tutorials to get started on your stuff. I wish Mono had tutorials (covering configuration, etc.) that were as good as Microsoft’s. I wish PHP did, too. Also Flex. I didn’t need a quickstart tutorial to figure out MySQL but I suspect there are a lot of developers out there who could benefit from one.
Actually, these platforms may very well have great tutorials, but I never run across them, which suggests to me that they’re missing something in the search engine optimization department.
I was talking with a prospective consulting client last week and we were trying to figure out where my services could fit in. I told them that while most of the consulting I do today pertains to product strategy, I’m not above doing super tactical stuff like technical documentation for them (as long as they realize that, as technical writers go, I’m on the pricey side). I offered to do this because good tech docs people are really hard to find and they tend to be unappreciated. I’m actually surprised that there aren’t consultancies specifically dedicated to doing technical documentation — maybe that’s because companies aren’t willing to pay for documentation the way they pay for software engineers.