Waterfox Errors and confusing documentation about browser-samples HOT 8 CLOSED

Thanks for the suggestions.

1. I've added a troubleshooting section to the README. In particular, I suggest developers look at the JavaScript console for errors.

2. For the Calendar Quickstart, we give an example of readonly access. The Google Calendar developer docs state how to create a calendar event and give a notice for the scope requirement. Perhaps we should state that you can remove the readonly scope to provide read and write access in the code as well? What would you recommend?

from browser-samples.

Sorry for the troubles. I haven't tested the tutorial on Waterfox.

Use of Mutation Events is deprecated. Use MutationObserver instead. -- bug-78414_content.js:70:2

The python just sets up a local HTTP server for your HTML file. You can also use Node, Go, PHP or any other language to create a local server for your page.

Can you create a local web server using the python code provided or using a different language?

from browser-samples.

Greetings Grant,

I must apologize as when I looked closer at the error it was not a file requested which in turn automatically implied that it was an internal Mozilla file (it is). The profile had suffered some minor corruption in the past though restoring an older copy and updating various things (bookmarks, password, session files, etc) I'm back to where I was without the issue.

That being said I do have a couple of suggestions.

First, please always clarify how the user is intended to test something and to check the console for errors. The example does work great for what it is.

Secondly, this code (var SCOPES = 'https://www.googleapis.com/auth/calendar';) should at least be noted that it has the readOnly bit that must be removed if one is going to create new events. I went so far as to write a blog entry because I saw a lot of people having trouble with that. Good testing is making sure you don't encounter any bugs, better testing is having someone else who has no idea try to setup it up without you saying a word. I consider my final testing to be finished only after I've shown people my work, typically I'll somehow find something wrong in those scenarios that I wouldn't on my own.

I'm not sure what the point of the serving testing is since it'll work live?

from browser-samples.

There is a bit of code and the best stuff to work with is intuitive and well documented. My first thought when creating an event would not work was that I somehow had not attached the authentication, though in retrospect that was an HTTP 403 error, not an HTTP 401 error. To keep the tutorial truly useful it must somehow continue to something new beyond just the basic quick start. By mentioning both why the read only scope is useful and to make the minor adjustment for (in example) creating an event you've not only greatly extended this tutorial you've also made it clear that deleting a few lines of characters will greatly open up what developers new to the API can do in a single seating.

I code very differently from the vast majority of developers and I do not find most other people's code intuitive, not a criticism, just a context of mindset. When I write my documentation for my web platform my goal is to understand what people are using it for and to make the tutorial as cooperative as possible. If I can avoid them having to go to a search engine or forum in order for them to continue on to their goals then I've succeeded in making my documentation useful. Your quick start tutorial is literally on that cusp with only these minor adjustments, at least for me. 👍

from browser-samples.

Can you state in short bullet points the last changes you'd like to see before closing this issue? We can also break up the problems into separate new GitHub issues to make discussing them easier.

from browser-samples.

1. Adjust step three to simply open the file on either a live web server as-is or if the Python server is for localhost testing please clarify that.

2. Add a Step 4 and clarify the SCOPES bit. I'd add either at least a link to the creating an event tutorial or add the code there with the clarification.

3. Add a Step 5 for the JavaScript documentation page. Now that you've already got a read-only and a write example it's easier for readers to detect the pattern (learning is the detection of patterns). I think this URL is it (I haven't really looked at it for a few days now): https://developers.google.com/calendar/v3/reference/

4. You've got the call-to-action(s) at the bottom, that's great!

That's really it, I believe. It's a good tutorial that just needs those extra finishing touches.

If you want to engage on individual issues I'd be happy to as I'll be working with the API to a fairly limited extent in the next few days. I'll let you close though please provide a link to the first new issue so I will know where we're working together at.

from browser-samples.

Whoa, I found a pretty severe bug and lots of people encountering it. I don't suppose you're around during the weekends too by chance?

#12

from browser-samples.

Hi! Grant's handed this issue off to me. To respond to your exact concerns:

Adjust step three to simply open the file on either a live web server as-is or if the Python server is for localhost testing please clarify that.

Our goal with these quickstarts it go get something up and running quickly, not to go into detail explaining how it works. We aren't trying to demonstrate the way to use the API, just one way to use it.

Add a Step 4 and clarify the SCOPES bit. I'd add either at least a link to the creating an event tutorial or add the code there with the clarification.

Ditto. There are many Calendar scopes and we have separate documentation that talks about them.

Add a Step 5 for the JavaScript documentation page. Now that you've already got a read-only and a write example it's easier for readers to detect the pattern (learning is the detection of patterns). I think this URL is it (I haven't really looked at it for a few days now): https://developers.google.com/calendar/v3/reference/

We already link to that in the "Further reading" section at the end. It's not required to get the quickstart to run, so it isn't a step.

I do appreciate your feedback, and we understand that developers would like a more gradual on-ramp into using the API in their target language / environment. At the moment we are relying on developers clicking through multiple pages (the JavaScript library's docs, the scopes page, the reference docs, etc) and we understand that isn't ideal. However it's outside the scope of this issue tracker.

from browser-samples.