it turned out that developers are using our documentation because they need to use it for the Android-specific classes, and it's just convenient for them to get all their documentation from the same place. plus a large proportion of external bugs are basically only solvable via better documentation: our code's working as intended, but people misunderstand those intentions.
--elliott On Thu, May 27, 2010 at 16:23, Jesse Wilson <jessewil...@google.com> wrote: > On Thu, May 27, 2010 at 4:04 PM, Joshua Bloch <j...@google.com> wrote: >> >> I was a bit surprised to see efforts being made to improve Android docs. >> The previous common wisdom had been "ignore them; everyone with any sense >> will read JDK JavaDocs instead." > > The new goal of our team is, "write better docs than the originals". This is > ambitious and will take a long, long time. But there are already a few > places where we've beaten the JDK. Embedded reference-guide docs like > Formatter and Pattern are now better organized and more task-oriented than > the Sun docs. Bogus APIs like InflaterInputStream.available() document why > they're broken rather than sweeping their problems under the rug. > We have a slight advantage over Oracle on writing these docs because we're > not afraid to point out mistakes. -- Elliott Hughes - http://who/enh - http://jessies.org/~enh/
