Feedback on GAW Cloudflare Workers tutorial #76
Description
This is my feedback on the Add Grid-aware Websites to an existing site with Cloudflare Workers tutorial. I’ve opened #75 for less substantial tweaks. I’ve ordered it matching the current sections of the tutorial so it’s a bit easier to follow. Feel free to close this issue if you don’t think the feedback is particularly actionable!
Overview
As-is, I think the tutorial is set up to demonstrate changes that are too specific to the Green Web Foundation’s Grid-aware websites page. I would recommend to change that drastically, to instead have the tutorial rely as little as possible on the "existing site" someone might be trying it out on.
This specific point from the overview:
Use the HTMLRewriter API to remove content from the page when a grid-aware view is recommended
I would suggest moving from an iframe element to something more generic. Personally I think a better "getting started" example would be to insert a "grid-aware yes/no" visible label on the page, say in the footer or just at the bottom of the body. Maybe change the page’s h1 to append "(grid-aware: on/off)".
And for this point:
Publish the Cloudflare Worker to target a specific route on your website
In my mind, one of the big strengths of the Cloudflare Workers approach is that you can get changes live to an existing site pretty fast. As-is, I don’t think the tutorial makes enough use of that. Personally I’d love to go straight to production on a real site if I can? But that’s only possible if the tutorial is adjusted to something that is both safer to push to production, and more generally applicable to sites. How about just generating a very simple "grid-aware demo page"?
In addition, regardless of whether you would want to take on the changes I suggested, I think it would be worth an acknowledgement in this section that we’re targeting a specific route for demo purposes – but in a real-world site there would most likely be a need to apply grid awareness across a wide range of areas of a site, or the whole site.
Before starting
Just to follow up on my points above – if you want to keep the tutorial contents as-is, I think this section needs an acknowledgement not just of the domain name in the examples but also the specific page. And recommendation on how to adapt the tutorial for one’s own site. But again I’d rather see the tutorial be made less dependent on existing content altogether.
Writing some code
Testing the code
If everything works, you should see the
Request from country code <SOME_COUNTRY_CODE>output in the browser.
This didn’t work for me, because wrangler dev returns a text/plain "Hello World!". I’m not sure if this is because I used the TypeScript template, or picked the wrong prompts in the create command in some other way.
Testing the completed worker
I mentioned above I’d recommend changing the tutorial so it’s less dependent on existing site content to test it. In addition, I think the tutorial would benefit from showcasing how to add custom response headers to understand what processing happened. In particular gridData.status and gridData.gridAware I think should be in headers.
The VPN and "set a fixed value" suggestions are reasonable, but they feel like they could take a lot of trial and error, compared to just copy-pasting code that has the headers to simplify troubleshooting.
Share your code with a colleague in another location and have them test it
Similarly I like this suggestion but I don’t think it’s realistic. I expect I’d have to ask a lot of colleagues to find one that’s in a different electricity grid. Assuming my team is distributed in multiple places.
So – I think the tutorial needs adapting to reflect this need for people going through it to troubleshoot their work. And ideally they should be able to do that autonomously, and ideally with only things they could copy-paste from the tutorial material, rather than involving a VPN or trial-and-error code changes.
Or – pick two specific countries that are guaranteed to fall in the "grid aware: on" and "grid aware: off" categories, and suggest them as examples.
Deploying to production
This is all making sense and working well. Here I would recommend adding more of a note of celebration – and possibly a call to action? "Share your grid-aware site with us"? "Provide feedback"?
Advanced
I’ve only read this section, didn’t actually go through with it.
- How to store and use data from Electricity Maps API to avoid making multiple requests for the same data.
I think the tutorial should acknowledge or cover how to deal with the Electricity Maps API being down, or just slow to respond (add a timeout at least). Either updating this point or as a separate one.
These are quality of life improvements to our code but while they are not critical, […]
I’m not sure about avoiding HTMLRewriter, but at least avoiding unnecessary reliance on the Electricity Maps API – that seems very critical to me, so the wording could be better here?
The specific concerns that I think the "advanced" tutorial should acknowledge are:
- Latency. My computer says 80ms for the Electricity Maps API. This feels like a lot of time to add to every request to a site. I’ve done zero research but I assume Workers KV is at least an order of magnitude faster? And a timeout is a must, I assume.
- Availability. Again I’ve done very little research but I would assume Workers KV uptime to be better than the Electricity Maps API.
And possibly also a wider nod to the energy use of fetching the data from Electricity Maps. Here again I’ve done no research, but would assume fetching from Workers KV takes less energy than an API call to a separate service with likely way more networking.