
New and improved Workers Docs - adamschwartz
https://blog.cloudflare.com/new-and-improved-workers-docs/
======
ignoramous
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.

~~~
kentonv
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.)

~~~
gravyboat
Hey Kenton. I recently migrated a few of my static sites to Workers and was
hoping you could clarify what the teams plan is around security headers. The
only documentation I could find was some random blog post from 2 years ago
that didn't help as the way workers function has changed since then and it's
no longer as simple as just dropping in a few lines of code.

I'd love to easily configure security headers so my sites are getting good
ratings again, but I couldn't find it in the documentation and it doesn't seem
like there's been any update to support this. Is your team working on making
security headers easier to enable for workers or is there something I missed
for setting this up?

~~~
kentonv
Hi! Hmm, not sure I understand. In a Worker, you can set whatever headers you
want on the response, in code. What problem are you running into exactly? What
do you mean when you say "the way workers function has changed"?

~~~
gravyboat
Sorry if I wasn't clear. Yes I understand I can set whatever headers I want in
a response via the edit options for my workers. The problem I'm running in to
is that I created a worker for a static site and it has a massive 1 line JS
blob for the script section that I have to go through to set this. I never
created this, it's just what was set up when I used Wrangler to deploy my
static site.

This is fine except it's a huge hassle to modify and I'm actually a bit
surprised that by default workers don't use secure headers. I figured they
would since they're pretty standard now and I'd rather have to disable them if
I needed then to manually configure them. If someone isn't familiar with
security headers there's also a good chance they would deploy their site and
never enable them which makes sites running on workers less secure by default.

I'm going off this several year old blog post:
[https://scotthelme.co.uk/security-headers-cloudflare-
worker/](https://scotthelme.co.uk/security-headers-cloudflare-worker/) that
talks about how to set this up and it seems like functionality has changed a
bit since then, or maybe I am misunderstanding their screenshots. Outside of
this I can't find any documentation from Cloudflare about setting these
headers that is more recent, or what I would need to set for a new worker that
has recently been created to get this functionality.

So I guess my question is two fold, are there plans to make it easier to
enable secure headers than to manually modify the worker itself? My plan is to
do that currently once I stop slacking and decide to just parse this giant JS
blob.

My second question is are there any plans to add documentation around
functionality such as this? I was really shocked to see that secure headers
weren't something that's simply enabled by default and even more so when I
looked through the docs and didn't see any examples on how to set them up.
Maybe my use case is niche, but I thought secure headers were pretty standard
at this point.

~~~
kentonv
Hmm, it sounds like you originally deployed your site using Wrangler, but then
you tried to edit it in the online editor. The code you saw was minified --
not intended to be edited directly.

The right way to edit the worker code is on your local machine before using
wrangler to publish it. There should be a file in your project directory like
`workers-site/index.js` which is your worker code in easily-editable format.

BTW, this file was copied from a template when you first generated the
project. Earlier this year we updated the template to set several security
headers:

[https://github.com/cloudflare/worker-sites-
template/commit/8...](https://github.com/cloudflare/worker-sites-
template/commit/8afe0a1d72a4018f096577b67cb97ab4ae450995)

But if you generated your project before that, you probably still have the old
code. If you haven't made any changes yourself, you might want to regenerate
your project so that it uses the latest template.

~~~
gravyboat
Okay that makes more sense and is just my bad then. I hadn't even looked at
the index thoroughly as the minified JS correlated to the `workers-
site/worker/script.js` and I didn't realize the index.js was responsible for
generating that based on content mismatch.

I generated my worker the second week of May so it's totally possible that
this wasn't in the release I generated with. Thanks for pointing out that the
template had been updated.

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

~~~
kaycebasques
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/)

~~~
adamschwartz
(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/contri...](https://developers.cloudflare.com/workers/docs-
engine/contributors-guide)

[2] [https://developers.cloudflare.com/workers/docs-
engine/docs-f...](https://developers.cloudflare.com/workers/docs-engine/docs-
flavored-markdown)

[3] [https://documentation.divio.com/](https://documentation.divio.com/)

[4] [https://git.io/JJAWP](https://git.io/JJAWP)

(edit: formatting)

~~~
itmightbecody
Fellow docs person here. Really like the new design—both in terms of
information architecture and actually browsing the site! It looks like your
docs engine is based on Gatsby. I'm looking into replacing our current static
site generator, and Gatsby's near the top of the potential list.

I haven't dug into the repo yet, but building your own docs engine atop Gatsby
seems like it would require a lot of additional config. Any major things you
needed to address that Gatsby couldn't do out of the box? And when you say
further use of the docs engine, are you open to other organizations
using/tweaking it?

~~~
adamschwartz
Gatsby is pretty powerful but also quite complicated and has a fair amount of
issues to deal with.

For example it was pretty unergonomic to set up support for deploying to a
`pathPrefix` [1] while retaining the ability to develop locally [2].

Nevertheless, we were able to make it work and have been relatively happy with
Gatsby overall.

Absolutely! The docs are dual MIT and Apache licensed [3] so have at it. One
note: we have not yet completely teased apart the so-called “engine” from our
particularly implementation itself. This is something we’re planning to do, in
part because we need to to support our other docs sites. You may find it
easier to work with once we’ve done that. That being said, you can also just
fork the repo, change the content and branding, and things should mostly “just
work”. Of course if you run into issues along the way, we’d be glad to have
contributions back to the project itself. Good luck!

[1]: [https://git.io/JUJsy](https://git.io/JUJsy)

[2]:
[https://github.com/gatsbyjs/gatsby/issues/16040](https://github.com/gatsbyjs/gatsby/issues/16040)

[3]: [https://github.com/cloudflare/workers-docs-
engine](https://github.com/cloudflare/workers-docs-engine)

------
eastdakota
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
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
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
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
OK, but, what's the problem with GitHub? I want to understand. Like, is this a
political thing, or is this a usability thing?

~~~
kentonv
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.

