That's a great suggestion from Andyw. It would be extremely helpful to have at least some comments inline explaining and documenting the processes and particular code.
Since the other suggestions are to have an interactive demo with an editable source window and then an area to run that code and see how it works, I would suggest a layout similar to what Dreamweaver at least used to use (I haven't used it in years), where there is a primary window - in this case, the iframe that would display the working code - with a floating source box that can be docked to the bottom of the window, moved anywhere else you might want it to go, resized as desired, minimized (akin to the windowshade effect Mac classic apps used to have, I suppose, where all you see is the title bar), or even closed. For a sample of such functionality, you could check out the editor I use in my CMS at the link below: http://www.woodward-granger.k12.ia.us/cgi-bin/molded4/template.cgi?m=directory&action=mailForm Click on the <> button at the end of the toolbar to see the source window appear. Please note, though, that the editor is not yet functional in Safari (it's a work in progress). You'll also see that the interface (i.e., the close, minimize, "zoom" buttons) also automatically adjust to either Mac OS X's gumdrop buttons in the upper- left OR Windows/Linux box buttons in the upper-right, depending on the client's UA. I think this would be a good thing, if only to provide to make a user feel more at home. 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 21, 2008, at 2:20 AM, Ben Lisbakken wrote: > 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.com domain 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 -~----------~----~----~----~------~----~------~--~---
