SDK documentation is the most official documentation and support material for developers to learn how to use the Application Programming Interfaces (APIs) the platform provides. The quality of SDK documentation directly affects the willingness and difficulty of the developers to create applications on that certain platform. However, in the current market, it's just so hard to find perfect SDK documentations. Most developers have to rely on extra information such as books and technical communities to do their development. What are missing from the SDK documentations? Why the developers don't like about the documentations? I think the lack of sample code, the lack of integration, and lack of innovation are some of the main reasons.
Lack of Sample Code
Many SDK documentations only explain what the APIs are, the methods and properties, and how to use them. But there aren't significant amount of sample code to show exactly how to use those APIs.
For example, let's look at the documentation of the ConfigurationManager class (http://msdn.microsoft.com/en-us/library/microsoft.windowsmobile.configuration.configurationmanager.aspx) in the Managed Windows Mobile Class Library. Suppose you are not an expert in developing device applications using .NET Compact Framework, can you figure out how to use the ConfigurationManager programmatically in a very short time? I guess not. It's not your fault, but the absent of some sample code. Though in this particular case there is a particular section in the Windows Mobile SDK which contains many sample applications, that doesn't help enough. Code segments are very necessary to be included along with the API descriptions.
But then let's look at the Address.AddressLine Property in the Live Search API Reference (http://msdn.microsoft.com/en-us/library/bb251813.aspx). In this case, thanks to the large amount of sample code, I'm positive that developers can get the idea very soon, because I personally do and I never developed any single application using Live Search APIs before.
The developers will still be able to figure out how to use the APIs without good sample code segments after some time, but if the sample is there, then the developers will be able to figure it out immediately. This shows the importance, the value, and the "magic" of the code segments that most current SDK documentations don't have, which is quite unfortunate.
Lack of Integration
Every single API is documented, but unfortunately, nobody knows how to use them together from the documentation.
Sample applications and starter kits do solve part of this problem and provide valuable information to the developers on how to use different APIs together. But looking at a sample application or starter kit with more than 500 lines of code just to know how to use two simple APIs together doesn't seem efficient.
I don't know whether there can be any good way to completely solve this problem, but creating more topics on how to use some of the APIs together seems to be a good idea, because these topics will be of high value. An SDK documentation certainly needs to have some low value contents to cover everything, but users need high value documentation, and the high value part is the set of contents that they will use and appreciate the most.
Users don't need information in using all the combinations of the single APIs (that will be huge amount of contents to create, but low value). The creator of the documentation should do enough user research to understand what combinations of APIs are of the highest demand, then create topics on how to use those APIs together. I bet the developers will like that. Well, don't trust me, your user research will tell everything.
Lack of Innovation
Every SDK documentation in the market looks similar in format and style. Every SDK documentation looks like a dictionary. As I mentioned above, it's necessary for an SDK documentation to include every public API the platform offers, but the documentation can be a lot more flexible in addition to that. The creators focused too much on trying to document every API and fix every bug, but invested too little on researching the users and finding new and innovative ways to present the information.
Then what are such innovative ways? There are a lot; and there are a lot that I don't know. As mentioned above, providing some topics of using certain combinations of APIs (of highest demand) is one possible way to improve the usability and value of the documentation. In addition, I'm also thinking about the way the contents being presented can be improved so that when a developer needs help on a task (note, a task, not an API), information such as the APIs he may use, samples, alternative approaches, etc should be available to the developer. Then the developer can grab the information he needs very easily, and complete the task easier than ever.
Creating high value SDK documentations is the same as creating high quality software products. Users are very important in the process. Formal user studies are very necessary in creating documentations, to determine what innovations can be done to best satisfy users' needs.
Such improvements need a lot of work to be done, and that's why we haven't seen this happen yet. But again, developers don't only need a "dictionary", they need innovative and high value support contents that ultimately help them finish their work. SDK documentation creators should really realize and understand this. But since the demand is there, I'm positive that I can see some innovations on SDK documentations in the future.
The good thing
The good thing is that every major company creating SDK documentations also provides community support materials such as webcasts, blogs, and forums to assist developers. In the mean time, if such community support can be continued, and at the same time adding more code segments to existing topics, creating more high value topics in addition to the dictionary of APIs, begin to do formal user studies on documentation, and do some useful innovations, then the whole customer (developer) experience will be a lot better. As an Independent Software Vendor programming on many different platforms, I really hope I can see that happen as early as possible.