Website Architecture Discussion

[capjamesg]

Before we begin developing the Open Web Advocacy website, we need to align on a few things:

1. What are the main goals for the website?
2. What information do we want to show?
3. What technology/technologies do we want to use to develop the website?

While making decisions on the above topics, we need to consider the following question:

What path will create the best experience for our website visitors?

Further, we need to consider the audience of our website. Who is our target visitor? What is the action we want to prompt when someone visits? Do we want people to join our community? Assist with advocacy? Something else?

[aliblackwell]

This sounds great!

I am going to mostly address point 3 on the basis that the answer to 1) is display public letter and recruit and display advocates, build mailing list, communicate report findings, and ultimately persuade Apple to allow other browsers and treat web apps as first class apps (and failing that to persuade the regulators to persuade Apple), and that 2) is everything needed for the above. But I defer to content already posted by Matthew in the Discord, and I look forward to a lively discussion on website audience and actions.

Continuing the theme of playing to the strengths of existing volunteers, I propose the following stack:

Postgres database

Hosted in the cloud or on existing project infrastructure.

Mailing list tool

This could be Buttondown as it has a nice API signup option, enabling us to have a single form for advocate and subscriber signup. (Or it could be our very own mailbag with some work to allow programmatic signups.)

Static site hosted on Netlify

• EleventyJS static site generator
• Markdown files for page, post, public letter and report content
• Semantic HTML templates
• Hand-crafted CSS based on designs produced by volunteer(s)
• Hand-coded, accessible HTML form for gathering advocates with basic client-side validation. Mailing list opt-in button (GDPR compliant).
• Serverless function for server-side form validation. Connects to Postgres database using credentials stored in environment variables. Also posts opted-in subscribers to mailing list tool.
• Serverless function that returns all advocates. Connects to DB and provides a JSON or markdown blob of all advocates. This endpoint is requested by eleventy during build, and is used to populate the template. We could even make this a manual process if we wanted to introduce any content moderation i.e. a site admin would manually view the endpoint and then commit latest advocates to the repository after editing to remove malicious submissions that got through form validation, which would trigger a build and a deployment.

If we wanted to implement @thescientist13's idea of publishing mailing list posts on the website, it would just be another post type in our eleventy config, with another directory of markdown files. Once a new post was merged into main branch and deployed, the URL could be grabbed from the site and sent out via the mailing list tool.

I believe this approach - using the JAMStack - offers our users the best experience as it empowers us to hand-craft the HTML, CSS and any JavaScript we choose to use. This will enable us to build a site that meets the Web Content Accessibility Guidelines 2.2, and is secure and privacy-friendly from the get-go. We won't use cookies, so we won't need a cookie notice; the data stored in Postgres will be as secure as data can be, and the purpose for which we're requesting it is directly related to the goals of the campaign.

I look forward to comments and suggested improvements for this approach, and I'm open to entirely different ones too!

[brunostasse]

Here are some thoughts that reply in part to 1) and 2). I also incorporated ideas Matthew shared in the Discord:

Targets:

• Possible OWA advocates
• OWA advocates
• Journalists
• Regulators/legislators
• Tech public

Goals relative to these targets:

• Inform and spread awareness about the issues we've identified as obstacles to the open web and their potential remedies to possible advocates, journalists, regulators/legislators and the tech public
• Explain in detail the issues/remedies for advocates, journalists and regulators/legislators to fully grasp them and use as reference in their discussions, articles, documents
• Expose how things can change and how people can help these changes
• Recruit advocates
• Inform journalists and regulators/legislators of how to contact us
• Collect coordinates for all people interested in learning more about these issues and their development

Content:

• Dedicated pages for specific issues and their remedies (like the Apple Browser Ban, in-app browsers, etc) with:
  • a tl;dr (like 10 lines max)
  • a succinct explanation (less than 2 pages)
  • a lengthy detailed explanation (no limit)
    • all sections should be linkable to (with anchor on titles)
    • system of footnotes for references
    • list of references
  • A FAQ to reply to specific points around the issue/remedies (like "Wouldn't opening iOS lead to a Chromium monoculture?")
  • Need to support good in page navigation between the different parts and sections
• A page listing the name (and more?) of all people supporting the "cause"
• A page listing all interesting resources around the issues (articles, Twitter threads, developer surveys, etc.)
• A blog for posting updates on:
  • new issues or remedies identified
  • new content on the website (new page for issues)
  • development in the industry or in regulation
• A way to subscribe to blog posts and news around OWA (a newsletter basically, not sure supporting RSS would be worth it)

Just some thoughts, I surely missed some important stuff!

[Andy-set-studio]

I'll put my hat in the ring to put together some design foundations and nice CSS that folks will be able to use to compose sections of the site.

Any tech stack that would help me work with HTML and CSS without much drama would be idea. I'll always give Eleventy a +1 for that.

[gericci]

@hankchizljaw I can help with the design and html/css either. I just don't want to step on others feet. How can we work together?

[Andy-set-studio]

I think for early design: Figma, because it's free to all. For HTML and CSS we will probably need someone to build out the core typography, colours etc, then everyone can get involved when a nice system is in place.

[thescientist13]

As far as content goes for the website (maybe a separate Information Architecture issue would be good?), just wanted to share some thoughts from the Discord chat.

I would say one of the key things this group can help bring to the table is the ability to help bridge the gap and provide context and technical literacy to the uninformed, especially more so for those who are in a position to enact change (people or politicians). Not saying we have to go as low as a "series of tubes" per se, but making the tech stuff more relatable to everyday folks is a great ability for those in our position to be able to do, and to articulate it into words for reference makes it all the more accessible and actionable.

Maybe we could include a glossary of terms or some very beginner friendly content / diagrams / illustrations to help bring everyone up to speed, which could help in the consumption and advocacy or more robust technical and policy heavy content? Illustrations and diagrams are a bit more effort, but there is the saying a picture speaks 1000 words.

Just my $.02.

[capjamesg]

@thescientist13 I love the idea for creating a glossary of terms that are relevant to browsers and the work we do. This would be useful for many parties, from our own community members to legislators to people interested in finding out more about our advocacy work. We would have to agree on a scope to ensure we don't define too many technical terms that are not relevant, as you mentioned in your message.

Perhaps we could get @mtom55's thoughts on this based on his experience writing documents for OWA.

[mtom55]

@thescientist13 I love the idea for creating a glossary of terms that are relevant to browsers and the work we do. This would be useful for many parties, from our own community members to legislators to people interested in finding out more about our advocacy work. We would have to agree on a scope to ensure we don't define too many technical terms that are not relevant, as you mentioned in your message.

Perhaps we could get @mtom55's thoughts on this based on his experience writing documents for OWA.

This is really important especially since some terms are not obvious to people who aren't deeply involved with the web or even browsers (i.e. terms like In-App Browsers).

Section 3.3 https://open-web-advocacy.org/files/OWA%20-%20Bringing%20Competition%20to%20Walled%20Gardens%20-%20v1.0.pdf of Walled Gardens contains a bunch of definitions

and Section 4 of https://open-web-advocacy.org/files/OWA%20-%20In-App%20Browsers%20-%20Subverting%20Competition,%20User%20Privacy%20&%20Choice%20-%20v1.1.pdf contains terms related to In-App Browsers (some of which I made up because no existing terms existed)

[capjamesg]

@mtom55 Would you like me to copy those definitions into a new Glossary page on our site?

[mtom55]

@mtom55 Would you like me to copy those definitions into a new Glossary page on our site?

Sure, might make a good start. Be nice to have #hashtag id's on them so that we can deep link