Andyw sent me this:Ben, >From a new user's point of view, I'd like to see much more inline documentation. When the example creates a map or calls for an object or calls the google site to execute a query, the code isn't articulate enough to convey its purpose despite the English-sounding names and properties. I'd like to be able to read through the code and know why certain calls are being made in the head or body and why they are made in a certain sequence. I'm guilty of this in my own code but, the model ought to be can I go back to this code a year from now and know exactly what was done, when, and for what reason. For a new user, this reasoning sequence is far more illuminating than the code sequence.
Thanks, Andy ------------------ Andy -- So comments in the code is king for you? I will try to write samples that are short (~10-30 lines) and I will add in a lot of comments. Will this help? -Ben On Mon, Oct 20, 2008 at 12:09 PM, Ben Lisbakken <[EMAIL PROTECTED]> wrote: > Matt -- > Getting it committed to Google code is actually going to be an easier task > and more beneficial for the community. Having it hosted on a > google.comdomain means that it must go through security reviews. An > application that > allows the user to run arbitrary Javascript on the google.com domain > undoubtedly raises some concerns ;) Also, all community-submitted changes > to the samples would have to be routed through me. I don't want to be your > tyrannous committer! > > Yeah, I like the idea of ordering the demos from easy to hard. > > I'm pondering a few things at the moment. I'm thinking the code should be > all Javascript, and just the most basic stuff. The HTML boilerplate code > (<html><body>, script includes, etc.) should be left out so that the samples > get to the point. Then, when the Javascript is run, the output could either > be an overlay iFrame that takes up the whole screen and shows the output, or > the code could be run and output in the existing document. There are some > pros and cons to both: > iFrame overlay: > - Pros > -- Encapsulates the code from the existing page, doesn't clutter window > object and cause global variables from multiple samples to clash > -- Shows clearly to the user that the next sample has been run > > - Cons > -- Slow (have to load a new document) > -- Obtrusive - can't follow code and look at output simultaneously > > > Run code on existing document: > - Pros > -- Fast > -- Intuitive, can run code and output simultaneously > > - Cons > -- Cannot use full browser screen, so only demos with minimal UI output > with width of a few hundred pixels will work/look good > -- Some hackery must be done to prevent global object collisions > > Any other ideas? Which one sounds better? > > -Ben > > On Mon, Oct 20, 2008 at 11:49 AM, Matt Foster <[EMAIL PROTECTED]>wrote: > >> >> I like this idea very much. I'd say as the content in the beginning >> may be sparse we'd want one page that covers all of the APIs. If >> things get overwhelming on that page information can always be spread >> out to become API specific, just branching from the main example page. >> >> Having everything in Google code would be ideal but may be a big >> initial hurdle in getting things going. Would certainly be a good >> thing to aim for but if it means taking a lot of time to deal with >> migration then perhaps focus on what can be launched soon and then >> work on coderizing everything in an incremental process behind the >> scenes. >> >> I especially like the idea of having an inline editor of sorts, I >> remember using w3schools variation of this all the time when first >> learning javascript and it gave me the ability to quickly understand >> things through empirical testing. >> >> In regards to the complexity of the examples i'd leave that to the >> natural order of the navigation, plainly said, Hello World at the top, >> Theory of Relativity at the bottom, as the user progresses through the >> examples the difficulty of understanding will increase, this seems >> like an adequate approach, I'd certainly shy away from any explicit >> branding such as labeling a given section with a "rating". >> >> >> On Oct 20, 1:17 pm, "Ben Lisbakken" <[EMAIL PROTECTED]> wrote: >> > Maybe it makes sense to have dropdowns for each API and just have a >> single >> > page.+ Search >> > - Feeds >> > > Hello World >> > > Historical Entries >> > > Result Count >> > > Custom HTML >> > + Libraries >> > + Language >> > >> > Also, it would be good to have it hosted on code.google.com so that the >> > community can contribute as well as pull it down. >> > >> > What are some common uses of the APIs that just aren't covered by the >> > documentation? >> > >> > -Ben >> > >> > On Fri, Oct 17, 2008 at 4:27 PM, Jeremy Geerdes <[EMAIL PROTECTED]> >> wrote: >> > > Great idea to create a central repository for code samples and >> tutorials. >> > > I think the basic samples that demonstrate key concepts are best, but >> I >> > > would also include a handful of advanced samples to get people >> thinking >> > > about what's possible. I would also say that, while a centralized >> > > repository for samples and tutorials is great, it will have to be >> > > categorized at some point to denote which API(s) the sample covers. >> Thanks >> > > for asking! >> > >> > > Jeremy R. Geerdes >> > > Effective website design & development >> > > Des Moines, IA >> > >> > > For more information or a project quote: >> > >http://jgeerdes.home.mchsi.com >> > > [EMAIL PROTECTED] >> > >> > > Unless otherwise noted, any price quotes contained within this >> > > communication are given in US dollars. >> > >> > > If you're in the Des Moines, IA, area, check out Debra Heights >> Wesleyan >> > > Church! >> > >> > > On Oct 17, 2008, at 4:04 PM, Ben Lisbakken wrote: >> > >> > > Hey all -- >> > > I've been looking through the samples and we have a decent amount. >> The >> > > only problem is that they're spread out and sometimes hard to find. >> Also, >> > > it's kind of a mix-and-match whether the samples are very low-level >> and easy >> > > to understand or whether they take a bit of involved thinking. >> > >> > > I've been toying with the idea of creating a page like the Maps API >> has >> > > like this: >> > > >> http://code.google.com/apis/maps/documentation/flash/examples/index.html >> > >> > > I'd like some input from you guys, though! I was thinking an >> interactive >> > > page where you can run all of the demos without having to click in, >> and even >> > > edit the code inline and see the changes. And what about the >> difficulty of >> > > the demos? Would it be more helpful to have very bare-bones basic >> samples >> > > that show very common uses that users ask or would you want to see >> > > mini-sample applications that actually achieve some goal? >> > >> > > And lastly, should there be one page for all of the AJAX API demos or >> > > separate pages for each individual API? >> > >> > > Please discuss. >> > >> > > -Ben >> > >> > > p.s. contributers welcome! >> >> >> > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Google AJAX APIs" 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/Google-AJAX-Search-API?hl=en -~----------~----~----~----~------~----~------~--~---
