Hi, i answered inline: On Wed, Aug 27, 2008 at 9:24 PM, ezCandlesticks <[EMAIL PROTECTED]>wrote:
> > I finally got around to actually looking at your article in detail > last night, and I have to criticize your article a bit. > PLEASE take this as helpful criticism. I mean no offense. And by the > way- what I wrote below is as much for EVERYONE writing articles on > Google as it is you. No offense taken :) Article feedback is something we want and we want to make them better. I will try to explain why i did what i did next.. > > You made the same mistake I keep seeing over and over on these Google > pages. – > You forgot who your audience is. Savvy programmers might catch on at a > glance, but you aren't writing for the savvy. You are writing for > beginners and every article should explain step by step and in detail > everything. We all try to make the articles as simple to understand as possible. Please also take into consideration (and this is no ofense to you this time :) that, if i'm guessing correctly, you're new to Google Desktop gadget development and some of the terminology (interface object names, etc.) may not yet be familiar to you. The thing to do isn't to 'blindly' read the documentation :D it's just making cool gadgets and travelling towards the purpose of that gadget you inevitably learn some specific terms. > > You made too many assumptions and you based your article on your > gadget specifically. I know a lot of authors do that, and it is > helpful to have a gadget to look at to follow the article. However, > your article has code snippets that to be honest when I first saw made > no sense. I had no clue what you were doing. So I got your gadget and > tore it open and then I understood. You created pages called > fetcher.js and parameters.js and had these in a folder called Objects. > That may have been obvious to an experienced coder, but I'm not that. > I had to get your gadget and study it to figure that out. Articles aren't exactly ment to be the first resource you should read. (Btw, this is my own vision, dunno what other developers think, but i'm guessing it's pretty right.) Don't forget the documentation, which tells you about UI elements, methods, APIs, etc. and maybe not even the samples, which emphasyse a certain feature of the API. Just as a tip: about the Objects folder, i don't think it should be obvious :) It's just what i believe a good way to organise my code. You can use any number of folders you want and split your Javascript code in as how many .js files you want (within reason :). > Articles should not require the reader to get someone's gadget to > understand. An article should be understandable as a standalone > tutorial, and the gadget can be extra. Articles should indeed be a standalone tutorial, but only including referred pages and resources (such as gadgets). There is the issue of length when writing an article; it's proven that a long article will bore the user and make him/her go away before they actually learn anything. It's very important to stick to a certain API feature or its relevance might be lost in explanations. But sometimes it's hard when you're writing an article to decide what you keep in and what will be cut. For example, a tip for other developers in this situation might be writing a more specific article and link to a full version explains every concept, like i did with my OOP article<http://code.google.com/apis/desktop/articles/e5.html>. > Going back to your article, write it the way a beginner will recognize > and understand. Combine your elements onto main.js or EXPLICITLY tell > the reader your example has things spread across three pages and give > a good reason why. Point out what difference it makes, and keeping > mind the readers are beginners, say things like "don't forget to > declare your new fetcher.js in your main.xml". > Honestly, I'm just trying to help you improve the article a bit. It > was helpful and gave me a good starting point, but I wasted half the > evening trying to figure out what the heck before I caught on to the > parameters.js. I doubt any beginner is going to know that setup. For > your article, just declare variables on main.js like a beginner would > understand. Well, i'm sorry you found it a bit hard to figure out, but, to your credit, the technique in that article is pretty complex. A dev should first learn how to make a functional gadget, and have that gadget done before applying an stats system. Again, i think articles are about giving insights once you hold the basic knowledge - when i develop a gadget, most of the time i do it keeping this web page<http://code.google.com/apis/desktop/docs/gadget_apiref.html>open at all times. It's true that things like "don't forget to declare your new fetcher.js in your main.xml" have to be said, sorry if i sometimes forget to say it, but i put special effort in finding the places where such things need to be said :) Anyway, the article submission/editing process has been continuously improved over time and this suggestion helps. > As I said, your article gave me a good starting point. As soon as I > got it working I realized this would fill the db table with tons of > useless data. So I redid it, some minor changes in the gadget and a > different approach with the mysql and now the table has "installed", > "installedDate", "removed", and "removedDate" fields being updated > based on "gadgetID" key. There is also a "status" field that gets > marked as "active" or "inactive". This keeps data entries minimal, and > more organized. I put a function in the onClose of the gadget to > signal the "removed" and the dbquery looks for matching entries based > on the gadgetID to either make a new entry or update an existing one. > But it still isn't that great. Every time the user closes the desktop > app or even reboots, it generates a new ID. My setup will give me an > accurate real-time view of how many gadgets are active, but I'd prefer > not to have a new entry for the same gadget/user. I seriously want a > want to store a gadgetID value more permanently, or possibly pull > something from the computer that would always be unique- like the cpu > ID or MAC address. So far, I haven't found anything that leads me to > believe that is possible. Probably a privacy concern. I'm looking into > user prefs- but I'm not sure if that'll work either. Anyway, thanks > for a good idea! It gave me a solid starting point. I'll consider this a technical question rather than article criticism so i'll answer accordingly: yes, you're right about the necessity of a unique ID and about the privacy concerns as well, but there is a solution in the article, i'll paste those parts here for you: Now that we think about it, more fields will be needed to for extra information. Why? Well, we could have a 'Parameters' field, which contains, let's say the version of your gadget for the 'install' action or a user ID for the 'confirm' action. This way we gain so much more extra information, like how many people install different versions of your gadgets. Notice that the user ID doesn't imply a feature available to the user, so it has to be generated in an anonymous way so it will help us only with gadget life stats. ... function _onOpen(){ //setting default options //... options.putDefaultValue("firstInstall",true); options.putDefaultValue("UID",new Date().getTime()); //getting a confirmation, and, if it's the case, an install notification var f=new Fetcher(); if (options.getValue("firstInstall")){ options.putValue("firstInstall",false); f.post(parameters.WebTvCentral,"install",parameters.version); } f.post(parameters.WebTvCentral,"confirm",options.getValue("UID")); } Notice how we get a unique ID, through the Date's object getTime() function which returns the number of milliseconds passed since 1970. :-) Keep in mind that this is not actually an ID, it's a key which allows us to group the confirmation messages and measure time lengths; everything is still perfectly anonymous. Extra actions which are triggered by users (like settings, feature use, etc.) should be fetched only with explicit permission; this can easily be done using a checkbox in the options dialog. I hope this helps. -- Teo (a.k.a. Teodor Filimon, Teominator) Site - www.teodorfilimon.com | Blog - www.teodorfilimon.blogspot.com GMT +2 (or PDT +10) --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Google Desktop Developer Group" 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-Desktop-Developer?hl=en -~----------~----~----~----~------~----~------~--~---
