Death To Outdated Developer Content
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.
I think Microsoft’s specific strategy for world domination makes them place a higher value on developer support and developer documentation than nearly any other organization in the world.
As Adobe becomes more comfortable in its new role as a developer-focused company (with the Macromedia acquisition, Adobe has a lot more developer tech than they used to), I’m hoping their documentation will improve.
Open Source documentation is never going to be as good as commercial developer documentation. Either it is written by volunteers, or it is written by an organization that makes their money selling support for the product.
Actually, I suspect that some of the larger open-source software companies may have excellent documentation that they simply don’t release to the public, because doing so is not in their financial interest.
The solution to the open-source documentation problem exists, and its name is O’Reilly– but it can sure be frustrating when there isn’t a book on the tech you want to work with.
As a side note– while I agree with you that Microsoft’s tutorials are excellent, your experience of starting with a web search, running into outdated content, and making many wrong turns before finding the tutorial you need is what happens to me pretty much every time I need to find developer content on Microsoft’s site. This is one aspect of the process that I’m amazed Microsoft can’t do better– organizing their documentation, linking outdated documents to the more current versions, and making the whole collection much more searchable.
Well, every company aspires to world domination. The difference is how successful they are and what they’ll do to get there.
My point is that tiny companies (and open source projects) should be able to do good documentation as well as big companies. It’s just a matter of defining “done” as “thoroughly documented”.
I think that open source documentation can be terrific. A while back I blogged about how much I like python.org — it’s one of the best developer sites around, and that includes commercial and open-source.
There are many documentation consultancies out there. Most of them focus on more than just writing — they’ll also put together an overall information architecture, and build complex content management systems as well. Mostly this is because of the very reasons you mention — documentation tends to be hugely undervalued in general by technology people, and documentation skills especially so (anyone can write, after all (sarcasm)). You can be a lot more successful and more valued as a documentation services company if you downplay the actual documentation. The majority of these consultancies — as far as I’ve seen — also tend to work for very large companies simply because those are the kind of shops where they’re more likely to need an information architecture and a content management system, etc, etc — all the infrastructure larger companies with large amounts of documentation need. Also the projects tend to be more stable and longer-term.
Small companies and OSS projects, in my experience, are more focussed on immediate needs and small projects — they need a manual right now for this particular release. Individual contract writers and volunteers are better suited for that rather than consulancies. But with individual work, especially volunteers, you definitely get a big variation in quality in the output. Especially if the company doesn’t really see long-term value in documentation in the first place, or doesn’t see the need to pay up for talent (admittedly the technical communication industry hasn’t been very good at explaining this value in the first place). Maintenance is especially where things tend fall apart. Even if you like to write documentation it really stinks to update it.
Personally I have found some Microsoft developer content to be excellent — the ASP.NET tutorials are the prime example. A lot of the .NET reference content is kind of inscrutable, though, and the navigation is just plain impossible. There have been dozens of times I’ve stumbled on an article on MSDN that explained exactly what I needed to know — and then lost it and never found it again. Drat!
With OSS documentation I’ve found that the popular projects generally have excellent reference documentation (python and PHP, notably). Excellent tutorial and procedural documentation is harder to find. Mostly this is simply a function of the volunteer effort — its easy to write a few reference docs here and there from time to time, and the nature of reference docs is easy to understand and to structure (pick a function, write about it. done). You need a deeer understanding of a project as a whole to write howtos or task oriented docs, as well as more skill in technical writing in general. People who are good at this kind of writing tend to be doing it for money rather than as a volunteer.
O’Reilly (and to a lesser extent the other book publishers) do a good job of filling in the holes in quality tutorial and procedural documentation for OSS. My only quibble with the ORA oevre is that since they focus on the technologists as authors the writing tends to be kind of fair-to-middling. But I’ve learned over the years that an author who is at the same time a good technologist, a good teacher, and a great writer is rare as hen’s teeth.
I seem to have spewed a rant all over your blog. I’m sorry about that.
Not at all, thanks for stopping by, Laura. This is great information.
I’ve been pondering for a while about a way to do open-source style collaboration on documentation in a more effective way. Not a content management system, not a wiki — maybe like a wiki with some structure.