On Tue, Dec 14, 2010 at 1:40 PM, Chefgon <[email protected]> wrote:

> Absolutely you shouldn't release new APIs unless you've had time to
> document them properly. Suggesting that releasing APIs is more important
> than documenting them is nothing short of absurd. Documentation is one of
> the most critically important aspects of any software platform and Android's
> is just plain bad. If your APIs aren't fully documented then they aren't
> finished and absolutely are not in a releasable state. Pushing them out on
> the world without proper documentation is irresponsible and causes serious
> harm to the platform.


Well I guess I will continue being irresponsible and harming Android.
 *shrug*  As I said, we do spend quite a bit of time writing documentation.
 It isn't as much as you'd like.  That's fine.  I doubt it will change.


> As an example of how important good documentation is: Google claims that
> third party apps will behave correctly across all the different manufacturer
> skins as long as the developers don't use any undocumented calls. Well, when
> virtually nothing is documented in a satisfactory way that leaves us with an
> unusable and hopelessly fragmented platform, wouldn't you say?
>

Spending a bunch more time improving documentation is about the *least*
effective way of addressing this kind of problem.


> Take some time off on the new features for a while and document everything
> that's already there thoroughly and completely.
>

Let's see, I have a list of features that are being demanded for a release,
many of them coming from our developers.  And I drop half of them to be able
to write better documentation.

I don't think this will fly.

-- 
Dianne Hackborn
Android framework engineer
[email protected]

Note: please don't send private questions to me, as I don't have time to
provide private support, and so won't reply to such e-mails.  All such
questions should be posted on public forums, where I and others can see and
answer them.

-- 
You received this message because you are subscribed to the Google
Groups "Android Developers" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/android-developers?hl=en

Reply via email to