Aug 21, 2013

Documentation? Again?

A year and a half ago I was already whining on the quality of documentation even of big companies. Since then the situation seems to get even worse!

I recently came upon this article - "Api Documentation" by Chris Parnin. The article is a research studying the fact that most developers are using StackOverflow as a main documentation source. I totally recommend to read the whole article, but here I'll just quote the main result of the study:
  • Developers may be getting as much as 50% of their documentation from Stack Overflow.
  • More examples can be found on Stack Overflow than the official documentation guide.
  • In web searches, Stack Overflow questions are visited 2x-10x more often than official documentation.

So why does StackOverflow is of more use for developers than official documentation? Simply because it answers questions that developers face. I.e. it covers the actual use-cases, which documentation does not!

But this is kinda strange - how come that documentation does not cover the actual use-cases? After all, the API was designed to allow its users to solve actual problems, right? So it should be clear how to solve these problems using the API, right?

I think we have an evidence that most APIs just were not designed with a thought of how and why it will be used in actual life! This explains why it's so difficult to write a solid documentation for those APIs. I mean, if it's so hard to explain the basic ideas behind the API, maybe - there are no such ideas?

As another proof I'll just point again to an example of a thought-through API which has a better documentation that I can remember - Berkeley DB Java Edition. Reading it's Getting started guide is a pleasure like reading a good adventure book - there's clearly a sense of plot, a scenario behind all the API! And it answers the main question - how to use it to achieve your goals! And as a result, it's functional reference (Javadoc) makes just more sense than any functional references ever saw!

So I assume - it's not that hard to make a good documentation for a good API, but you have to design a good API first! If you have thought of how your API will be used and why, it's never a problem to explain this in words! (Looking on how to make a good API? You may want to start with Joshua Bloch's speech "How To Design A Good API and Why it Matters").

Not too great design

Now, there's even more. I'd like to quote a part of the article's introduction captioned "Why it sucks":
Now, the trend may shift even more of the undocumented burden onto developers. The YouTube API recently moved their official developers support from Google Groups to Stack Overflow (Move)— relying on a few thousand questions about the API and on mechanisms of Stack Overflow. And there is no sign in sight that documentation is all the sudden going to get better.
So instead of learning from StackOverflow on how to improve the documentation, the API providers are thinking that developers will make the documentation as well! That's amazing! But this is where they are going.

For example let's take Unity3D site. It has separate documentation section and Unity Answers which is a clone of StackOverflow but hosted by Unity and integrated into it's "community" section. That seem to be a nice idea, right? Well, at least the implementation is bad. First of all, if you expect Unity developers to give answers in "Unity Answers", you are wrong. Next, if you expect that nice answers for popular questions will get integrated into main documentation (which is pretty bad!), you are wrong again! In fact - nobody cares!

Another example is described in this post - "8 months in Microsoft, I learned these". Here's a quote:
Not giving back to the public domain is a norm. I haven’t met almost any bloggers or open source developers in my organization dedicating some of their time to give back to the community. Everybody loves finding Stack Overflow answers on search results, but nobody contributes those answers. I can understand that.
So, if the corporations are not doing proper API design, not documenting their public APIs, not even care to give answers on StackOverflow and such, why do they make APIs public after all? To earn money for providing paid support? Anyway, they don't care about us, developers, after all.

No comments:

Post a Comment