Blinkk Build Plan

Introduction

Who should read this

This document should be read by all project stakeholders including, but not limited to, product/service/growth marketing managers, analytics and tracking systems owners, technical directors, and QA team members.

Objectives

This plan documents the approach the Blinkk team will use to ensure that all team members are aware of the approach they will take to build and launch the website.

Goals

1. Build a highly-performant, high fidelity website that matches supplied visual designs.
2. Empower the marketing/website team to own the end-to-end website workflow, while the engineering team (if applicable) can focus on building out the product/service.
3. Achieve best-in-class ratings for site technical performance, SEO performance, and other related metrics. We strive to build an excellent user experience that loads as fast as possible, which we believe positively impacts the website’s KPIs.
4. Maintain accessibility best practices.

Team Structure

Blinkk team

Role	Responsibility
Engineer Manager	Oversees high-level implementation. Assists in connecting technical and business needs of client to the engineering team. Assists with technical priority setting and decision-making. Assists with configuration of build and deployment systems and flows.
UX Engineer	Conducts all front-end development work. Conducts all template and project structure setup.
Producer	Connects design and business needs of client to the Blinkk team. Conducts all project management internally within the Blinkk team. Helps communicate updates from Blinkk to the client.

Responsibilities

• All front-end technical development and configuration.
• Faithful execution of designs delivered by the design team.
• Initial copy and asset placement required for the launch.
• Workflow setup and project management related to the build.

Technology

We are using a home-grown, open source static site generator to build a fully static (HTML, CSS, JS) website that will be deployed to Google App Engine as static files.

Description	Product	Justification
Static site generator	Amagaki	Highly optimized for marketing workflows and marketing/informational websites. Used in several hundred Google projects. Keeps website performance high, and website structure foundational and maintainable for the future. Localization inbuilt. Our home-grown solution (made exactly for projects like this).
CSS preprocessor	Sass	Leverage BEM for modularity and maintainability.
JavaScript	TypeScript	Pursue “No JS” solutions when possible, to minimize the amount of JavaScript that has to be built and maintained. Use Lit.dev for simple UI state management and for elements that require reactivity (e.g. an on-page list of data that is generated from a feed).
Web server	Google App Engine	We deploy a simple application to proxy our static files and handle any dynamic paths such as redirects. Redirects and on-domain vanity URLs are managed inside a YAML file in the repository.
Code hosting	GitHub	GitHub easily integrates with Google Cloud Platform and our build pipeline.
Build tool	Google Cloud Build or GitHub Actions	By using Google Cloud Build, we do not need to leverage another third party service and we keep all configuration in one simple place. GCB is fast and low-cost. GitHub Actions can be used as a replacement for Google Cloud Build for projects hosted and managed on GitHub.
Image server	Google App Engine images service	Fast, free, and supports incredible real-time image transformation and compression.
Analytics and tracking	Google Tag Manager	This is our recommended default
DNS	(TBD or N/A)
Domain registration	(TBD or N/A)
Monitoring	StackDriver error reporting	Sends email notifications whenever critical errors are encountered.
File hosting	Google Cloud Storage	Any files (such as downloadable PDFs) or other media meant to be downloaded, will be hosted on Google Cloud Storage and linked to directly from the website.
Issue tracking and project management	Asana, GitHub, or Buganizer

Design and Development Workflow

#TODO - Should we link to the Design handoff section here?

Deployment

Overview

We heavily leverage Git branches to prescribe our workflow:

• main mirrors the live environment.
• feature/xxx branches contain feature requests and enhancements.
• During the pre-launch phase of the project, all work is conducted in main.

Builds are initiated via Google Cloud Build and GitHub integration.

• Builds take approximately 30 seconds to 5 minutes to complete.

Staging

• All non-master branches are automatically staged to isolated staging URLs.
• Once a Git commit is made to a branch, Google Cloud Build initiates a staging build.
• Staging URLs are accessible to the project team only.
• Access to the staging URLs is controlled via the Identity-Aware Proxy (IAP).
• Blinkk will provision everyone@domain.com access to the staging environment, so the client team can view all staging environments automatically.
• The staging environment is accessible on both desktop and mobile, so that real mobile devices can be tested.

Going live

Once a Git commit is made to the master branch, Google Cloud Build initiates a production build and deployment. Generally, the build and deploy process takes between 30 seconds to 5 minutes (depending on the technical complexity of the build and the number of pages).

Reverting changes

If a mistake was made, it’s easy and quick to roll back changes. Just revert the Git commit in main and a subsequent build will initiate. We have a full history of every change (and associated time)

Monitoring

We don’t expect the website to go down due to errors on our part, for any reason.

• If we have made a critical code error, the issue is caught during the build phase, and the build fails to deploy. This prevents users from encountering critical errors.

StackDriver monitoring is used to catch two types of errors:

• A JavaScript bug or code error on the client-side. We are alerted to JavaScript errors in the staging environment.
• Uptime issues with the live website. We expect to be alerted only if the site is critically down, such as due to system-level downtime (i.e. from Google Cloud Platform). This type of failure is out of our control, but we accept the risks. We use GCP and Google App Engine for hosting extremely high traffic websites without issue. GAE guarantees 99.95% uptime.

Localization

Blinkk will build the site to be localizable in the future. Our build process supports:

• Message extraction into catalogs that can be used to translate strings
• Generation of localized files (with one per supported locale)

Messages can be translated by a professional translation service, or a translation proxy such as Smartling can be used. We will rely on the client team to provide any localized data, such as localized images, product pricing, metadata, etc.

Best practices

SEO

Blinkk will build the site to adhere to SEO best practices. On top of building to optimize our PageSpeed performance scores, we will implement:

• Canonical tags
• Appropriate meta tags for social networks
• Appropriate share images for social networks
• Reasonable URL path structures
• Microdata tags as appropriate
• Appropriate structure for page titles and descriptions

Adhering to SEO best practices is a team effort. While Blinkk will do everything possible on the technical side to ensure we follow SEO best practices, SEO scores take into consideration numerous signals, and ultimately one of the most important factors of SEO is the content (i.e. website copy) present on the website itself. We can provide guidance but rely on you to craft the right copy and page descriptions.

Additionally, another important signal in SEO is inbound links: if a page has no inbound links from other well-ranked properties, the page will not rank very high. We rely on you to ensure that the website is linked to from other properties, and appears appropriately in press sites, blog posts, etc.

A note on URLs

There is a long-held belief in the SEO industry that declares that content hosted on subdomains impacts domain reputation negatively. According to Google, this is false. Google Search treats subdomains and domains the same. There is a lot of material on SEO websites that says differently, but official material from Google indicates subdomains are treated as internal links, not external links. Avoid trusting what sketchy "SEO best practices" websites may claim without verifying the claims with an authoritative source.

Prerequisites

• Verification: All properties should be verified with Google Search Console.
• Sitemaps: Sitemap files for each domain should be submitted to Google Search Console.
• Links: Links between the subdomain and main domain properties should exist.

Evidence

• Google Search Central: Reorganizing internal vs. external backlinks
• Google Search Central: Subdomain or subfolder, which is better for SEO? (1 min 45 sec): “Google Web Search is fine with using either subdomains or subdirectories [...] Pick a setup that you can keep for longer. Some servers make it easier setting up different parts of a site as subdirectories. That’s fine for us. [...] On some servers, using subdirectories for different sections like a blog or shop can be trickier, and it’s easier to put them on separate subdomains. That also works for us.”
• Directly relevant Twitter thread where @JohnMu stands behind the Google video (scroll up to see the thread history)
• Supporting documentation on Cloudflare

More SEO notes

• John Meuller on headings and how headings are used by Search, summarized on Stackoverflow

Accessibility

Blinkk understands the importance of building websites to be accessible, and usable by as many individuals as possible. We use the Web.Dev Accessibility Guide as a baseline for accessibility best practices. We will implement:

• Keyboard navigation and focus states
• Aria settings and element roles
• Alt text

Blinkk builds to be accessible, but accessibility is a team effort. In addition to the above technical considerations, we need the following from the cross-functional teams to reach proper accessibility:

• Color contrast of designs and UI components (text, etc.) must be sufficiently high
• Proper alt text (copy) must be written for images
• UI labels in website copy should be clear and actionable

Performance

Performant websites are important for SEO and usability, and also make interacting with the site a more pleasant experience. We will test our build against PageSpeed Insights and aim to achieve scores above 90 on both mobile and desktop for critical pages of the website. We will implement:

• CSS splitting, to load critical CSS first and to reduce initial paint time
• Image lazy loading using native loading=lazy to reduce initial paint time
• Dynamic image serving and (compression, file formats, etc.) leveraging Google’s dynamic image service
• “No JS” solutions when possible, leveraging native CSS and HTML methods such as CSS scroll snapping, CSS smooth scrolling, etc. To improve on-page performance, we will leverage JavaScript as little as possible but as much as necessary.
• Micro-optimizations such as JS/CSS payload reduction and usage of rel=preload
• Static file serving, to reduce TTFB (time to first byte)
• Network/CDN caching (i.e. with Cloudflare) to minimize server-side work

More than any other best practice, performance is truly a team effort. The following non-development areas must be taken into consideration in the context of site performance:

• Over-use of assets and large media in design: very large images and videos take a long time to load. Image and video usage should be minimized, compressed, or carefully chosen.
• Over-use of tracking and analytics scripts: every analytics or tracking ping consumes network and CPU resources. A few tracking and analytics pings are OK, dozens are not.
• Over-use of intensive interactions and animations: certain animations and transitions perform better than others. Intensive scroll-locked or scroll-jacked animations (i.e. image sequences, or CSS clip-path transitions) may put significant pressure on the CPU when the user scrolls,
• Over-use of high fidelity interactions on mobile: Mobile interactions should really be kept simple, minimal, elegant, fast, and small. Mobile users really benefit from speedier pages, more than anything, and should never have to wait. Every millisecond counts and can impact the “pleasantness” of mobile site usage.

Desktop and mobile responsiveness

We will build the website to work well on all screen sizes and devices. Certain designs may look and behave differently on different viewports. If there are design elements that may create problems on certain screen sizes, we will flag them to the team and discuss them.

Forms

Many sites have forms – for example, lead capture forms, email submission forms, survey forms, etc. Blinkk isn’t responsible for collecting or managing leads, so launching a form will be a cross-team, collaborative process. Usually, the form is a critical component of the page, so it’s important to get things right.

To launch a form, we need an HTML snippet that demonstrates a working form. We can then style it and embed it within the website experience. In lieu of an HTML snippet, we need:

1. A full list of form fields, including the user-facing labels and the IDs (where the IDs are the keys used in the form submission, in the code).
2. Whether any form fields are required.
3. Whether any form fields have specific validation (e.g. whether values must only come from a select list).
4. Whether there are any hidden field IDs, and their values.
5. Testing parameters – such as whether we should expect a "success" result from the server, and/or the ability to self-test by receiving a confirmation email from the testing environment.

Lastly, all stakeholders (e.g. the folks managing and collecting leads in the backend) should perform an end-to-end test in staging prior to launching the form.

Testing and QA

Dedicated QA

Blinkk does not have a dedicated QA team or dedicated QA resource. Our UX Engineer and Producer teams run through basic testing and validation (as outlined below). We can engage with a QA partner or dedicated QA team if desired, however it is out of Blinkk’s development scope.

Test plan

Blinkk runs through the Blinkk Test Plan with every major launch. The Test Plan covers:

• Basic responsive (desktop and mobile) functionality
• Whether the build matches the design
• Basic tracking/analytics implementation
• SEO and microdata verification
• Accessibility features
• Basic functionality of forms and submission flows
• Basic browser compatibility

Browser compatibility

Blinkk’s development scope ensures compatibility with evergreen browsers. “Evergreen browsers” are modern browsers that self-update with functionality enhancements, bug fixes, and security updates from their vendors. We target:

• Google Chrome (desktop and Android)
• Safari (desktop and iOS)
• Firefox
• Edge

Notably, we do not target IE in our compatibility matrix as IE is not an evergreen browser. IE usage is incredibly minimal worldwide (source).

Communication and issue management

Development

All development tasks will be tracked in Asana/Buganizer. In lieu of meetings, developers will update the Notion board at the end of each day to communicate progress. In Asana/Buganizer, stakeholders can:

• View timeline and milestones and adjust dates accordingly
• See development progress by page
• View the progress of any additional tasks and/or larger features

Blinkk will reach out to stakeholders directly if any roadblocks, issues, or concerns arise.

Visual QA (VQA)

The design team will be responsible for filing VQA bugs in Asana/Buganizer once staging is completed. In order to swiftly fix issues, we ask the design team to provide:

• A description and screenshot of the issue as it exists on staging
• The URL to the page where the issue is present
• Redlines or written guidelines of the expected fix

QA

Stakeholders will file QA bugs in Asana/Buganizer once VQA is completed. If timelines overlap, stakeholders will be responsible for viewing the VQA board BEFORE filing bugs to ensure there are no duplicate bugs. Stakeholders will be responsible for the following:

• Assign a project manager to train their team on how to use Asana/Buganizer and file bugs correctly. The Blinkk team will provide instructions and guidance.
• If a design issue is filed, assign it to the design team and ensure clear action items and deliverables are passed to the development team.
• Manage any bugs that are assigned to the stakeholder team and route accordingly to the development team once they are ready to be actioned.

Maintenance

New feature requests or bugs

Enhancements or new bugs (regressions) should be filed in Asana/Buganizer, with appropriate priorities. Blinkk is alerted, will acknowledge the issue, and either stage the fix for review or push the fix live (once the site is launched) immediately, if critical.

Priorities, lead time, and response times

It’s important to align on priorities across the team. “When everything is P0, nothing is.” See the priority level definitions in the following section.

Priority level definitions

Pre-launch (visual QA, functional QA)

Priority level	Description	When it’s actioned
0	The issue is critical and must be fixed prior to launch, as it impacts core functionality, security/performance, or the website’s design/brand. Examples include: Primary CTAs or interactions not working (i.e. buttons, site navigation, etc.) Incorrect website copy or assets Obvious design flaws	Before the site launches
1	The issue is an obvious layout or interactivity issue, but isn’t critical to the website’s functionality or the design. Examples include: Minor design flaws Secondary functionality or interactivity not working (i.e. returning to the start of a carousel)	After all P0 issues are resolved (unless there are low-hanging fruit)
2	The issue is considered a minor cosmetic issue or a non-critical feature request. Examples include: Spacing and padding issues Design flaws on uncommon viewports	After all P1 issues are resolved (unless there are low-hanging fruit)

Post-launch (maintenance and bug-fixing)

Priority level	Description	When it’s actioned
0	Severe issues involving core broken functionality/data loss, security or user privacy issues, or issues that could result in critical harm to the client’s brand or revenue.	ASAP
1	Obvious functionality, layout, or interactivity issues that are clearly broken.	1-3 business days
2	Non-urgent content or functionality issues or updates not tied to a specific launch date.	3+ business days, prioritized against other tasks

Maintenance

Content management roles and responsibilities

• Blinkk builds all modules to be reusable, meaning they can be duplicated and different content (website copy, images, etc.) can be placed into new instances.
• Blinkk will input all website copy and images for the initial launch of the website.
• Modules used in new and unexpected ways can cause breakages if they were not built to handle the inputted copy or data. Once the Live Editor is available (see Live Editor section below), we will ask the client team to input copy and asset changes into the Live Editor, so they can be made without developer involvement.

Self-service changes

Blinkk’s initial focus is on the build and launch of the website. We design our build process to be easily maintainable by us, or other developers. We would welcome being your “outsourced webmaster” team in the long-term, after the project launches.

• Git users (or engineers) can easily make changes to any portion of the website, safely, with minimal knowledge of the website structure.
• Optimization/experimentation, analytics or tracking instrumentation should be primarily handled in a third-party tool without requiring a developer (i.e. Google Tag Manager or Optimizely).

Editor.dev

In a later phase of the project, we will deploy Editor.dev, a page-building CMS that is integrated with Git, which integrates with Amagaki and our website codebase. Editor.dev can be used in a self-service manner for activities such as:

• Updating copy and images
• Re-ordering modules on pages (see design caveats)
• Creating net new pages using existing modules
• Quickly previewing changes

Editor.dev will not be available for the initial launch of the project, but will complete its setup, deployment, and training in a later phase.

Changes best handled by a developer

While some activities (as outlined above) can be performed in a self-service fashion, certain activities may be best handled by a developer. Examples of changes that are best handled by a developer may include:

• Implementing changes to interactivity or functionality
• Creating net new modules based on net new designs
• Creating and testing elements that require connections with other systems (such as forms that submit data)

Blogs and long-form content

We will not make any changes to the blog as part of the initial project launch. We will develop a build and deployment plan for the blog in a later project phase.