7 ms·

New and improved Workers Docs

53 points by adamschwartz 6y ago

eastdakota 6y ago
Here’s a blog post on the process and rationale: https://blog.cloudflare.com/new-and-improved-workers-docs/ https://blog.cloudflare.com/new-and-improved-workers-docs/
- cxr 6y ago
  It sure would be nice if there were an off-GitHub way to help you guys with your docs. Before this new revamp, I spotted a link whose redirect had disappeared. I resorted to emailing someone on staff, and they filed an issue about it, but it was an experience that's pretty far removed from the efficiency of a wiki.
  - kentonv 6y ago
    The docs are on GitHub: https://github.com/cloudflare/workers-docs-engine https://github.com/cloudflare/workers-docs-engine By "off-GitHub" do you mean you'd prefer there were some other way to edit the docs directly? Mind if I ask why?
    - cxr 6y ago
      The repo is linked all over the docs. It what I used to track down the problem. > By "off-GitHub" do you mean you'd prefer there were some other way to edit the docs directly? Yup.
      - kentonv 6y ago
        OK, but, what's the problem with GitHub? I want to understand. Like, is this a political thing, or is this a usability thing?
        deleted 6y ago
        [deleted]
        kentonv 6y ago
        Not sure why your reply was deleted, but FWIW... > https://www.colbyrussell.com/2020/05/13/psa-wikis.html https://www.colbyrussell.com/2020/05/13/psa-wikis.html Forking a github repository to edit one file and submit it back as a PR is super-duper easy these days. You can do it entirely from the UI by just clicking the pencil icon when viewing the file you want to edit. I'd argue the only real difference from a classic Wiki is that you need to submit the change for review. There's really no practical way we could eliminate the need for review.
gyre007 6y ago
This is so much better than the old docs. I'm super bullish on workers as a next-gen computing platform.
- kaycebasques 6y ago
  How is it better? (I read the blog post [1], as a technical writer I'm curious to hear people's first impression about which changes are most impactful) [1] https://blog.cloudflare.com/new-and-improved-workers-docs/ https://blog.cloudflare.com/new-and-improved-workers-docs/
  - ishcheklein 6y ago
    Yep, also interested in this. I'm writing and managing (among other things) the team at https://dvc.org/doc https://dvc.org/doc and had a lot of discussions like "How do we name and structure the high level navigation items"? From what I read in the blog post (and even considering how much the need to explain the change) this split `Tutorials, How-to guides, Learning` is still confusing to me, to be honest. So, would be great to get more opinions. (@kaycebasques cool stuff with Lighthouse and other docs, btw!)
  - adamschwartz 6y ago
    (Designer of the docs) We also published as part of this release some documentation for the so-called “Docs engine” which powers these new docs, which may somewhat answer this question. https://developers.cloudflare.com/workers/docs-engine https://developers.cloudflare.com/workers/docs-engine (Note: They currently live within the Workers docs site for now but will get a proper home soon.) With respect to the information architecture and content design, much of that is discussed in the Contributor’s Guide [1] and Docs-flavored Markdown [2] pages. The very short version is that we borrowed many ideas from Divio’s documentation system [3], which recommend dividing your content into four distinct buckets: Tutorials, How-to Guides, Explanation, and Reference. The layout and visual design were inspired by dozens of other docs sites we tested and studied, stealing the best ideas we could from everywhere we looked. It’s also worth noting that the Cloudflare Workers docs have been open-sourced for over a year now [4], and these new docs (as well as the new engine which powers them) will continue to carry the same license. Contributions are welcome and we’re hopeful and excited to see further uses of the docs engine over time. [1] https://developers.cloudflare.com/workers/docs-engine/contributors-guide https://developers.cloudflare.com/workers/docs-engine/contri... [2] https://developers.cloudflare.com/workers/docs-engine/docs-flavored-markdown https://developers.cloudflare.com/workers/docs-engine/docs-f... [3] https://documentation.divio.com/ https://documentation.divio.com/ [4] https://git.io/JJAWP https://git.io/JJAWP (edit: formatting)
ignoramous 6y ago
Big fans of Workers here. It has made our developmental, operational, and deploymental nightmares go away. ...but we've consistently seen users complain about latency and we have observed Cloudflare does not run Workers in the nearest location to the user. This can been semi-confirmed via https://cloudflare-test.judge.sh https://cloudflare-test.judge.sh Our endpoints are always routed to a destination which is not the nearest whilst other enterprise and business domains get served from a nearer location. This can also be confirmed using Coudflare's own https://www.cloudflare.com/cdn-cgi/trace https://www.cloudflare.com/cdn-cgi/trace endpoint (substitute www.cloudflare.com with any of your Workers endpoint to see how differently it is routed. I've been told it might be fickleness of anycast routing and it could be). Disappointing since it is hard to get customer service reps to look at your support tickets when you're on a "free account" (despite paying for Workers). We have no use for Cloudflare's other products and so it doesn't make sense to purchase pro/business subscriptions. That said, I'd still recommend using it since it so darn fast. Edit: Apologies to everyone for an unrelated rant. It was impulsive. I'm unable to delete this comment.
- foota 6y ago
  This isn't terribly surprising to me, they might not have the compute deployed in all their sites to serve the more expensive worker requests.
- kentonv 6y ago
  To clarify: - Workers run in the colo that received the request. We currently literally have no capability to forward Workers requests to other colos. (It's possible we'll introduce that in the future, but it's not the case today.) - Enabling Workers does not affect how your traffic is routed to colos. So if you're seeing Workers requests not going to the closest colo today, then regular non-Workers requests wouldn't either. It sounds like the issue here is that your base Cloudflare plan is the "free" plan (confusingly-named because you're separately paying $5/month for workers on top of that). When we have a colo that doesn't have enough capacity to handle all the local traffic, we often route free-plan traffic away from it, and they end up landing at the next-closest colo. This is completely unrelated to Workers -- it applies to any kind of Cloudflare traffic. If you upgrade to a higher plan level (e.g. pro at $20/month), you should see this happen much less often, if ever. Sorry that this is confusing! We should probably document this better. (I'm the lead engineer on Workers.)

53 points by adamschwartz 6y ago

Here’s a blog post on the process and rationale: https://blog.cloudflare.com/new-and-improved-workers-docs/ https://blog.cloudflare.com/new-and-improved-workers-docs/

cxr 6y ago
It sure would be nice if there were an off-GitHub way to help you guys with your docs. Before this new revamp, I spotted a link whose redirect had disappeared. I resorted to emailing someone on staff, and they filed an issue about it, but it was an experience that's pretty far removed from the efficiency of a wiki.
- kentonv 6y ago
  The docs are on GitHub: https://github.com/cloudflare/workers-docs-engine https://github.com/cloudflare/workers-docs-engine By "off-GitHub" do you mean you'd prefer there were some other way to edit the docs directly? Mind if I ask why?
  - cxr 6y ago
    The repo is linked all over the docs. It what I used to track down the problem. > By "off-GitHub" do you mean you'd prefer there were some other way to edit the docs directly? Yup.
    - kentonv 6y ago
      OK, but, what's the problem with GitHub? I want to understand. Like, is this a political thing, or is this a usability thing?
      - deleted 6y ago
        [deleted]
      - kentonv 6y ago
        Not sure why your reply was deleted, but FWIW... > https://www.colbyrussell.com/2020/05/13/psa-wikis.html https://www.colbyrussell.com/2020/05/13/psa-wikis.html Forking a github repository to edit one file and submit it back as a PR is super-duper easy these days. You can do it entirely from the UI by just clicking the pencil icon when viewing the file you want to edit. I'd argue the only real difference from a classic Wiki is that you need to submit the change for review. There's really no practical way we could eliminate the need for review.

gyre007 6y ago

This is so much better than the old docs. I'm super bullish on workers as a next-gen computing platform.

kaycebasques 6y ago
How is it better? (I read the blog post [1], as a technical writer I'm curious to hear people's first impression about which changes are most impactful) [1] https://blog.cloudflare.com/new-and-improved-workers-docs/ https://blog.cloudflare.com/new-and-improved-workers-docs/
- ishcheklein 6y ago
  Yep, also interested in this. I'm writing and managing (among other things) the team at https://dvc.org/doc https://dvc.org/doc and had a lot of discussions like "How do we name and structure the high level navigation items"? From what I read in the blog post (and even considering how much the need to explain the change) this split `Tutorials, How-to guides, Learning` is still confusing to me, to be honest. So, would be great to get more opinions. (@kaycebasques cool stuff with Lighthouse and other docs, btw!)
- adamschwartz 6y ago
  (Designer of the docs) We also published as part of this release some documentation for the so-called “Docs engine” which powers these new docs, which may somewhat answer this question. https://developers.cloudflare.com/workers/docs-engine https://developers.cloudflare.com/workers/docs-engine (Note: They currently live within the Workers docs site for now but will get a proper home soon.) With respect to the information architecture and content design, much of that is discussed in the Contributor’s Guide [1] and Docs-flavored Markdown [2] pages. The very short version is that we borrowed many ideas from Divio’s documentation system [3], which recommend dividing your content into four distinct buckets: Tutorials, How-to Guides, Explanation, and Reference. The layout and visual design were inspired by dozens of other docs sites we tested and studied, stealing the best ideas we could from everywhere we looked. It’s also worth noting that the Cloudflare Workers docs have been open-sourced for over a year now [4], and these new docs (as well as the new engine which powers them) will continue to carry the same license. Contributions are welcome and we’re hopeful and excited to see further uses of the docs engine over time. [1] https://developers.cloudflare.com/workers/docs-engine/contributors-guide https://developers.cloudflare.com/workers/docs-engine/contri... [2] https://developers.cloudflare.com/workers/docs-engine/docs-flavored-markdown https://developers.cloudflare.com/workers/docs-engine/docs-f... [3] https://documentation.divio.com/ https://documentation.divio.com/ [4] https://git.io/JJAWP https://git.io/JJAWP (edit: formatting)

ignoramous 6y ago

Big fans of Workers here. It has made our developmental, operational, and deploymental nightmares go away. ...but we've consistently seen users complain about latency and we have observed Cloudflare does not run Workers in the nearest location to the user. This can been semi-confirmed via https://cloudflare-test.judge.sh https://cloudflare-test.judge.sh Our endpoints are always routed to a destination which is not the nearest whilst other enterprise and business domains get served from a nearer location. This can also be confirmed using Coudflare's own https://www.cloudflare.com/cdn-cgi/trace https://www.cloudflare.com/cdn-cgi/trace endpoint (substitute www.cloudflare.com with any of your Workers endpoint to see how differently it is routed. I've been told it might be fickleness of anycast routing and it could be). Disappointing since it is hard to get customer service reps to look at your support tickets when you're on a "free account" (despite paying for Workers). We have no use for Cloudflare's other products and so it doesn't make sense to purchase pro/business subscriptions. That said, I'd still recommend using it since it so darn fast. Edit: Apologies to everyone for an unrelated rant. It was impulsive. I'm unable to delete this comment.

foota 6y ago
This isn't terribly surprising to me, they might not have the compute deployed in all their sites to serve the more expensive worker requests.
kentonv 6y ago
To clarify: - Workers run in the colo that received the request. We currently literally have no capability to forward Workers requests to other colos. (It's possible we'll introduce that in the future, but it's not the case today.) - Enabling Workers does not affect how your traffic is routed to colos. So if you're seeing Workers requests not going to the closest colo today, then regular non-Workers requests wouldn't either. It sounds like the issue here is that your base Cloudflare plan is the "free" plan (confusingly-named because you're separately paying $5/month for workers on top of that). When we have a colo that doesn't have enough capacity to handle all the local traffic, we often route free-plan traffic away from it, and they end up landing at the next-closest colo. This is completely unrelated to Workers -- it applies to any kind of Cloudflare traffic. If you upgrade to a higher plan level (e.g. pro at $20/month), you should see this happen much less often, if ever. Sorry that this is confusing! We should probably document this better. (I'm the lead engineer on Workers.)