Initial design plan

[adamschwartz]

Workers design planning

Here we’ll discuss the initial plan for the design of the Built with Workers site. This document was put together by @adamschwartz and @signalnerve with help from @remyguercio and based on research and input from the broader Workers team.

Terminology

• Project – a website, API, service, etc. built partially or wholly with Workers.
• Feature badge – a feature of Workers (e.g. Workers KV) that a project may use, displayed in a way to associate it with the project.

High-level goals of the site

Each goal is listed in a rough priority order. Meaning, for our MVP, we seek to achieve goal 1 stronger than goal 4. Note though that these are somewhat overlapping goals, and design is an art as well as a science, so it’s OK if we’re not strict here.

1. Answers the question "What can I build?"
   • Directly answers this question for anyone interested in Workers.
   • Gives Sales and Support the power to answer that question when it comes.
2. Showcases real projects
   • (As opposed to examples say in the docs which would be more for learning and thus stripped down and not necessarily live production apps/services.)
   • Bonus: a featured project can function as a sort-of case study, perhaps containing quotes or other supporting material to make a stronger case.
3. Provides a consistent experience with the Workers homepage
   • Intuitive and coherent navigation between the two helps synthesize concepts, particularly when deep linking between the two occurs. (For example, the item view page for a project built with Workers Sites linking to the Workers Sites landing page.)
   • Begin to mature and solidify the Workers brand.
4. Helps people "put the pieces together"
   • e.g. How do I use Workers Sites with HTMLRewriter?
   • Bring clarity to complex docs by telling a coherent story.

Features

These are also sorted in rough priority order. Same lack-of-strictness applies.

• Listing page
  • Default to manual sort (e.g. via order property similar Cloudflare Apps)
  • Listing page item
  • Project title
  • Project image
  • Feature badges
    • Icons
  • Project source
    • Avatar (user/company) image
    • Link
  • Featured boolean
  • Difficulty level?
  • Allow user-enabled sorting (date added, alphabetical, popularity [claps])
• Individual project page
  • Everything from "Listing page item" above, plus:
  • Project description
  • Optional image gallery
  • Optional quote
  • Claps¹
  • Edit link to GH issue with prefilled content
• Open-sourcing the Built with Workers site itself

[1]: We’re particularly excited about using Workers KV to build this (and showcasing that as Built with Workers itself will likely be a featured project of the site—yes, how meta of us).

Not doing (for MVP)

Here are a few of the things we considered building but decided against for the MVP. By no means should this list be considered exhaustive. We are happy to consider them after we slap down a v1.

• Feature pages (KV, HTMLRewriter, Wrangler)
  • Hero art
  • Descriptions
• Examples of features of an app you can build (a login flow, a redirect, an optimized image)
  • Live code feature examples with preview
  • Code as reference
• Admin author display ("signalnerve edited 4 hrs ago")

Potential list of feature badges

We think feature badges are going to be really fun. But we’re not sure exactly how they’ll work. We may have categories of these which could be distinguished e.g. by color.

• Workers features (proper badges) (orange)
  • Workers KV
  • Workers Sites
  • HTLMRewriter
  • WASM
  • Cache API
• Things that supercharge you (blue)
  • workers.dev
  • Github Action
  • Wrangler
• Tools to help you build with Workers (purple)
  • React
  • Gatsby
  • Svelte
  • etc.

Content

We plan to take a content-driven approach for the initial design. This is generally a solid approach to design, but it’s especially critical when designing a site whose content is generated by someone other than the designer.

Projects

The main content of course are the projects. So, with the help of @remyguercio we generated an initial list. If you know of know of any projects we missed, please let us know!

• Cloudflare & Employees
  • https://www.cloudflare.com/products/cloudflare-access/
  • https://workers.cloudflare.com/
  • https://developers.cloudflare.com/workers/
  • https://web.scraper.workers.dev
  • https://lazy.invoice.workers.dev/
  • https://www.bytesized.xyz/
  • https://repo-hunt.signalnerve.workers.dev/
  • https://github.com/signalnerve/bridge
  • https://github.com/signalnerve/workers-graphql-server
  • https://github.com/signalnerve/cloudflare-workers-todos
  • https://ritakozlov.com/
  • https://blog.cloudflare.com/fast-google-fonts-with-cloudflare-workers/
    • https://www.perftests.com/googlefonts/
  • https://blog.cloudflare.com/real-urls-for-amp-cached-content-using-cloudflare-workers/
  • https://workers.dev
  • https://docs.google.com/document/d/14SpeA8E79aDzCKfdkb9edjl3vSLKc6OWNFcPojz-nR4/edit
• External
  • https://www.happycog.com/
  • https://yogainternational.com/
  • https://www.propublica.org/
  • https://blog.optimizely.com/2019/09/12/performance-edge/
  • https://telex.blog/
  • https://www.digitaloptgroup.com/
  • https://factoriomaps.com/
  • https://github.com/lukeed/svelte-ssr-worker
  • https://github.com/bcnzer/cloudflare-worker-template-auth0-jwt
  • https://levi.lol/url-shortener-built-on-cloudflare/
  • https://blog.cloudflare.com/the-samknows-cloudflare-platform/
  • https://jross.me/free-personal-image-hosting-with-backblaze-b2-and-cloudflare-workers/
  • https://jross.me/using-cloudflare-workers-htmlrewriter-to-extend-ghost-pro/
  • https://www.cloudflare.com/case-studies/cordial-workers-black-friday/

Mockups

I know y’all want to see pretty pictures. I promise, they will soon exist. However, at this stage we feel it’s more important to share the plan, get feedback, and build consensus before drawing a bunch of rectangles.

[exvuma]

How does this all fit in with tutorials? Wondering if one goal could be to create a clearer organization of the featured tutorials? e.g. GraphQL Worker has a full-blown tutorial how will this link from the tutorial in the docs to the built with Workers? Could this be where the tutorials intended for specific purposes (e.g. React app, localize a website, ..) live instead of the docs?

For Goal #2, this seems more of a "what" than a "why". What is the goal of showing real projects built with Workers?

• Is it to advertise and promote the reliability and enterprise-grade quality of Workers as a platform (i.e. industry is building serious stuff with Workers)? If so, maybe we should include what are Cloudflare built applications versus external?
• Or is it to spring ideas of what to build with Workers. If so, I think that really fits in as goal #1.

[adamschwartz]

These are great questions! Thank you so much.

Re Tutorials: I’d like to know how @signalnerve, @neynah, and @ashleygwilliams feel about this, but my gut says that Tutorials would be an explicit non-goal for this site. Of course we can always link from say the description of a project to anywhere (including a tutorial living in the docs), but I think we should scope out anything more involved than that.

Re Goal #2: As I mentioned, the goals are a bit overlapping. So I definitely agree it overlaps with Goal #1. The two key ways I’d say it is distinct and make it worth listing separately are the following:

• As I mentioned the design of the site will be very content-driven. Therefore, how we curate the content is part of the design. This goal helps ensure we’re seeking to include and feature projects made by Workers consumers with the intention of them being used for real. Projects built by someone from our team e.g., while they may be real to an extent, they’re also often us testing or demonstrating what Workers can do, so they’re not as real in the sense that they’re not purely genuine efforts to create a product or service (that just happen to use Workers as their technology choice).

• Your first bullet point. We of course see this site as a way to market Workers. And what’s a stronger way than to showcase real products built by companies or individuals for which visitors of the site may be familiar with or trust. Real projects build trust and "fake" projects can create skeptics.

[kristianfreeman]

my gut says that Tutorials would be an explicit non-goal for this site. Of course we can always link from say the description of a project to anywhere (including a tutorial living in the docs), but I think we should scope out anything more involved than that

yes – this will live on workers.cloudflare so it should be thought of as conceptually different than tutorials/docs content generally. i think the docs redesign is a better spot to iterate on tutorials/how-to content for our audience

[exvuma]

Questions on tutorials convo above:

1. How do we handle and manage the redundant / conflicting content of tutorials and built with Workers for users? (i.e. If I google search "Cloudflare Workers Graphql" I might hit the built with workers site first, how would I be informed/directed to the tutorial? )
2. How do we internally determine whether to add a tutorial or a built with Workers page?

One solution might be to exclude all tutorials from the built with Workers site. (e.g. Remove graphl server from this list), but there would still be a problem with #2

[adamschwartz]

Re: 1 Ah, gotcha. That helps me understand your original comment better.

I think your suggested solution is probably correct then. As per goal #2 above, a tutorial we built is probably not the right thing for us to showcase on Built with Workers since it’s not "real".

On the other hand, if a project we initially built as a tutorial starts to get legs outside of our own use of it, then I could potentially see it deserving a place in both worlds. If that ever happens, I’d be happy calling that out somewhere on its Built with Workers page and linking back, which I think would solve the organic search problem you mentioned.

All of that being said, I would hope that a few months from now, this site consists almost entirely of more weighty external projects.

Re: 2 Since content is such an important part of the site, we should definitely draft guidelines around submissions, which would hopefully answer your question and many others. Eventually we may want to have a sort of notoriety criteria similar to Wikipedia. Initially, I imagine we’ll want to be more liberal in letting anything on since at this point we have a very small list of external projects.

I’m not sure how much of this aspect of the plan is known. At this point I think the plan is to curate enough project manually in order to just get an initial design going.

---

Thank you for these are great questions @victoriabernard92. Please keep ‘em coming!

[adamschwartz]

While we didn’t quite get to everything here, most notably "feature badges", I’m closing this for now since it’s not particularly actionable. We should still continue to use it as a reference post-MVP GTM but we shouldn’t consider not completing everything above as a blocker for release. Instead we’ll create individual issues as needed.