Core Marketing Site Architecture Plan

1. You are here:
2. Handbook
3. Marketing
4. Digital Experience Handbook
5. Core Marketing Site Architecture Plan

On this page

• What We Are Proposing
• What We Are Not Proposing
• Goals and Measurement
• Pages We're Focusing On First
• Scope
• Roles
• Needs
• Scope
  • Benefits
  • Risks
• Definitions

Why We Are Proposing This Change

Over the course of FY21 and FY22 it's been challenging to prioritize and make progress on the Monorepo Project. The lack of improvement to the developer experience is compromising the Digital Experience team's efficiency and we're not able to deliver our team's true output.

GitLab's Marketing site is also experiencing several technical issues that affect our current and prospective customers due to the complexities of our current repo. Digital Experience is not able to effectively solve and release fixes quickly which is undoubtedly causing GitLab to lose potential customers.

After considering 3 different approaches we've aligned on the following as our best option.

What We Are Proposing

1. Making key business driving pages of GitLab's Marketing site build faster, resulting in increased engineering output. Anticipated ROI includes:
   1. Pipeline times: currently we are at about 20 minutes average pipeline time. There are some work items that we need to see in the review app (anything requiring a data file), which means it can take 20 minutes to validate a change.
   2. Merge train times: since we work in a shared repository with the handbook that receives so many MRs so often, our work ends up in long merge trains. Looking at a recent production deploy on 2021-07-23, this MR took closer to 40 minutes to go live.
   3. Development feedback loop: running the Middleman preview server (our local development environment) by itself can take 3 full minutes to reload changes to our codebase. We implemented a monkey patch on Middleman to cut that down, and reduced it to 46 seconds. Benchmarks here. But the monkey patch doesn’t work on data-driven routes, so as we move more and more content into Netlify CMS, we spend more and more time waiting on three-minute refreshes in development.
2. Decreasing size of Marketing site repository to ensure stability
   1. As of 2021-07-23 the files in our repository take up 2.6GB of space. But GitLab registers it as over 68TB of storage overall.
3. Connecting Storybook design system platform with Marketing site to increase design & engineering output
   1. Current state: engineers build a single component twice. Once in vue.js in Slippers, and one in www-gitlab-com in ruby
      • Future state: engineers build a Vue.js single component in slippers. This component can be directly used in Nuxt.js

What We Are Not Proposing

1. Changing anything to the current processes of the Handbook
2. Changing any processes to the pages not identified as part of this project

Goals and Measurement

Ultimately this plan will reduce the time, money, and resources required to meet our team goals. Specifcally we will look to measure:

1. Reduce the time it takes to push a change to production
   1. Local build time
   2. Pipeline time
2. Increase the frequency of MRs
3. Decrease time to close issues
4. Decrease negative effects on Infrastructure and SRE team

Pages We're Focusing On First

We plan on starting with important pages that are simpler with lower risk, gradually increasing in value and risk.

1. Enterprise
2. SMB
3. Free Trial
4. Pricing
5. Homepage

Scope

• 6-8 weeks with 2 engineers
• Targeting 5 pages fully transitioned with the remaining page listed below in Scope being completed through Q4

Roles

DRI: @laurenbarker

Team Members Involved and Why

• @laurenbarker: Senior Fullstack Engineer who is most familiar with our tech stack, needs, and requirements.
• @tywilliams: Excellent engineering (specifically Ruby) skills required for this project.
• cwoolley-gitlab: Chad will be a stable counterpart and consult in this effort. Chad's involvement to date as well as his knowledge will greatly increase the success of this project.
• @mpreuss22: Product Management. Digital Experience team leader, accountable for successful delivery of this effort.

Needs

We will require GCP Deployment Keys from Infrastructure. We would also like a new storage container to enable the plan we have for the new build process.

Scope

1. Move 10 - 25 marketing webpage to new static site generator repository
   1. Pricing
   2. Homepage
   3. Free Trial
   4. Sales
   5. Demo
   6. Install
   7. Features (Landing and single)
   8. Topics (Landing and single)
   9. Solutions (Landing and single)
   10. Enterprise
   11. SMB
   12. Partners (Landing and single)
   13. Comparison Pages
2. Switch to Nuxt.js as SSG
3. Seamless integration with Slippers for efficiency and developer experience
4. Static site generator builds and deploys these 10 - 25 pages to the existing about.gitlab.com domain
5. Digital Experience team reduces maintainance of the www-gitlab-com repository
6. Iteratively migrate parts of marketing site to new repo over FY23
7. Buyer Experience Repository

Benefits

1. Increased output on key business driving page
2. Minimizes breakage for pages like the release post
3. Sets up a migration plan we can continue to work on as new pages become prioritized

Risks

1. Will need very clear documentation to ensure clarity of what lives where
2. We will most likely need support from Infrastructure
3. Duplication of dependencies on both sites (until entire Marketing site is moved to new architecture)
4. Negative impact to other teams' workflows as we move the single source of truth for some pages elsewhere.
5. Time estimation on related tasks will be inconsistent and incorrect as we learn what to anticipate with a new codebase.

Definitions

1. Core Marketing Site: Key pages that drive ARR
2. ARR: https://about.gitlab.com/handbook/sales/sales-term-glossary/arr-in-practice/
3. Vue.js: https://vuejs.org
4. SSG: Static Site Generator
5. Nuxt.js: https://nuxtjs.org