Diane, with all sympathy and respect, I think there is room for improvement.
On Dec 14, 3:01 pm, Dianne Hackborn <[email protected]> wrote: > 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. I dunno about that. You're very bright people. And motivated, and dedicated, too. I think if you took 10% of the time you now spend on documentation, just 10% more, and looked around, and thought "What is the most effective use we could make of this additional 10%, where it would really count, that 10% would have a very substantial impact. And I think it might about pay for itself, too, in time you don't spend answering questions here, and even in time you don't spend later reworking code, because when you tried to document it you found holes. >From my viewpoint (which may be atypical, dunno), I'd like to see half of that 10% spent in making the existing documentation more precise. Just a few more words here and there to remove ambiguity or to cover all the cases. Perhaps there's a way to leverage community involvement in reviewing the documentation, and flagging and prioritizing the areas where the time would really pay off. I think one of the challenge that you face is that this is really Google's show in a real sense, rather than a broad-based community effort. That's a whole complex set of tradeoffs across a multi-variate spectrum; it's unlikely you've found the *optimum* point, and you may be able to shift some of that workload to the community. > Spending a bunch more time improving documentation is about the *least* > effective way of addressing this kind of problem. [referring to fragmentation > due to use of undocumented calls] I quite agree, but I think there's a confusion here you didn't address. I think the original comment really was referring to non-public APIs under the label "undocumented calls". They're really different things. Fragmentation comes from people using non-public APIs, or manufacturers adding public-but-proprietary-non-standard APIs. Poorly- documented public API calls have little impact on fragmentation unless they drive people to using non-public APIs or cause confusion about what's public or non-public, or lead people to depend on behavior of public APIs that is not part of their actual contract. That last point is one reason I'd like to see a bit more emphasis on making some of the existing documentation more specific. But one defense against fragmentation is to provide the necessary functionality through new, well-thought out public APIs. And clearly, that's a race against time -- and adds to your documentation load as well. So when some of the documentation seems, well, hasty, I assume that's the explanation! Of course, I'd like to see Google hire more writers and developers, and give you a raise, too! -- 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
