Understood. I'm sorry you question the value to the doc writers of all this. Have you not used the MySQL or PHP documentation? Part of the real benefit is to the developer community themselves. It helps them converge their discussions around particular parts of the API. It lowers the barrier to contributing to the documentation (which in turn can help the tech writers), but perhaps the tech writers want a higher barrier, and prefer to have developers have to make extra effort to submit corrections or thoughts about the documentation, i.e. they don't want to wade through hundreds or thousands of low effort comments. Anyhow, it's not just about correcting the documentation, but allowing the discussion to evolve around the documentation components. I think any user/developer working with MySQL or PHP documentation would sing the praises of the open comment framework they use - it is just so fantastically useful.
Of course in the Java world not being able to add comments to documentation is the default. Anyway, it's just a suggestion. Even if you don't think it has much merit I would be most grateful if you would pass it on to either the tech writers, or whoever has responsibility for taking care of the android developer community. I think it's a fantastic idea with benefits all round, and many others in the open source world agree; I think it would make the process of developing for android hugely more efficient, and I'd love to pass on the idea, but whatever works eh? CHEERS> SAM On Aug 31, 7:59 am, Dianne Hackborn <[email protected]> wrote: > I don't manage the docs, so I can't really address your request, except that > the tech writers have very limited time and I doubt they will be able to > spend it on setting all of this up. I also question value to them of this, > since this would be a significant investment in time for monitoring all of > this, synchronizing with the real documentation, etc. > > If you want to contribute to the docs, they are there in source control open > to any contributing a patch, which a number of people have done already. > > > > On Mon, Aug 31, 2009 at 10:28 AM, tansaku <[email protected]> wrote: > > > Good to know that you guys are accepting contributions to the > > documentation in its current location. I can imagine that it would be > > a big task to move it elsewhere, but what about mirroring it to the > > google group discussion pages? That way any updates to the main > > source tree would be reflected in the google group documentation - > > both services are Google internal right? My main desire is not so > > much that everyone can freely edit the android documentation as in > > wikipedia, but that discussions about it can be directly linked into > > parts of the API. > > > I think it might actually make your job easier as you would have at > > least some of the discussions organized around the API. I think it > > would also lead to more focused discussion in the group, and not > > require developers to waste time trying to find which of 8 discussions > > on the same topic provide the correct answer to their problem. And it > > would lower the barrier to entry to making suggestions for changes in > > the documentation. > > > At the moment if I see something in the documentation that doesn't > > make sense, or is even just out of date, what do I do? I have to open > > a mail client, cut and paste, work out who to email to? Wonder if > > anyone will care if I do. If the android source tree was mirrored > > into the google groups pages, I could just hit the comment button and > > make my suggestion, knowing that it would also be there for others to > > see, even if the google developers working on Android didn't have time > > to look at it. That means you'll get much more feedback. > > > Just my $0.02 > > > On Aug 27, 6:38 am, Dianne Hackborn <[email protected]> wrote: > > > The official location of the documentation is in the source tree, in the > > > source documentation files and various java docs related to all of the > > > classes. We have been regularly accepting contributions to that code to > > fix > > > and improve the documentation there. > > > > Someone could certainly copy the docs to wherever else they want, but > > they > > > are going to have a fair amount of work cut out for them to keep those in > > > sync with the official docs. > > > > On Thu, Aug 27, 2009 at 7:44 AM, Balwinder Kaur (T-Mobile USA) < > > > > [email protected]> wrote: > > > > > I think that is quite a nice idea :) > > > > > As we come across ways that we feel can make the documentation become > > > > more succinct and report those, it helps Android Developers' lives > > > > become easier. The strength of an open source platform comes piping > > > > the knowledge of its users back into the platform. > > > > > Balwinder Kaur > > > > Open Source Development Center > > > > ·T· · ·Mobile· stick together > > > > > The views, opinions and statements in this email are those of the > > > > author solely in their individual capacity, and do not necessarily > > > > represent those of T-Mobile USA, Inc. > > > > > On Aug 26, 6:37 pm, Michael Leung <[email protected]> wrote: > > > > > But that needs someone to update it. I think that is fine to read > > from > > > > the > > > > > main android site. > > > > > > However, that is a good and positive idea. > > > > > > On Thu, Aug 27, 2009 at 9:32 AM, tansaku <[email protected]> wrote: > > > > > > > Hi All, > > > > > > > I was thinking, wouldn't it be great if all the android reference > > > > > > documentation was in the pages section of this Google Group, i.e. > > > > > > stick everything in here: > > > > > > >http://developer.android.com/reference/packages.html > > > > > > > in here: > > > > > > >http://groups.google.com/group/android-developers/web > > > > > > > then everyone could comment on specific bits in the reference docs, > > > > > > and even get involved in trying to improve them? > > > > > > > CHEERS>S AM > > > > > > -- > > > > > Regards, > > > > > Michael Leunghttp://www.itblogs.infohttp://www.michaelleung.info > > > > -- > > > 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. > > -- > 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 -~----------~----~----~----~------~----~------~--~---
