Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Website Handbook

Objectives

Serve the needs and interests of our key audiences:

  1. Users of GitLab: software developers and IT operations practitioners.
  2. Buyers of GitLab: IT management, software architects, development leads.
  3. Users of and contributors to OSS on gitlab.com.

Generate demand for GitLab by:

  1. Showcasing the benefits of the most important GitLab features and how they can save time and money.
  2. Compare GitLab vs competing products.
  3. Provide customer case studies which illustrate 1 and 2.

Scope

The GitLab marketing website, or simply the "GitLab Website" refers to all of the content on https://about.gitlab.com except the blog and handbook.

The website does not include

See Where should content go? to learn which web property is the most appropriate place to put different types of content. To learn what section of the website different content belongs see definitions.

Definitions

Topics

A topic is an industry trend, theme, or technology related to GitLab and our customers. For example, DevOps, GDPR, Containers, etc. Topic pages on our website educate the reader about the topic and share GitLab’s point of view while providing additional links to resources related to that topic. These pages are intended to attract search traffic.

Topic pages should exist at the root level of the website without being nested inside of another directory. e.g. /continuous-integration

Examples of other companies who have topic pages:

Solutions

A solution is a combination of products and services that solve a business problem. For example, accelerating software delivery, enabling remote teams, ensuring compliance, etc. Solution pages on our website show the application of GitLab capabilities and services to address a business problem while providing additional links to resources related to that solution.

Solution pages should be nested inside of the solutions directory. e.g. /solutions/continuous-integration

Examples of other companies who have solutions pages:

Product section

The product section of our website has pages that describe what GitLab does and the value provided. The functionality of GitLab is ordered in a hierarchy with 4 levels: Stage, Categories, Capabilities, and Features. You can find details on the Product Categories Handbook

Category pages should be nested inside of the product directory. e.g. /product/continuous-integration

Examples of companies who have product/features pages: https://mailchimp.com/features/ https://www.groovehq.com/features

Compare sections

There are two comparison sections on our website, /compare/ and DevOps tools.

The DevOps tools section provides an in-depth, feature by feature comparison of GitLab and our competitors. Pages in the DevOps tools section are maintained by the Competitive Intelligence team, which is part of the Strategic Marketing team.

Pages in /compare/ are shorter and focused on a single Call to Action that offers relevant resources to visitors arriving via paid advertising. Pages in /compare/ are maintained by Digital Marketing Programs and Marketing Program Managers.

Examples of companies who have comparison pages: https://postmarkapp.com/compare/sendgrid-alternative https://www.zendesk.com/support/features/zendesk-vs-intercom/

Overlap

Similar content can appear as a topic, solution, and in the product section with different emphases on each page. For example continuous integration:

Ownership and responsibilities

Everyone can contribute to the marketing website. While the Strategic Marketing and Pipe-to-Spend teams have primary responsibility over the website, the goal of these teams is to build systems, structures, and processes and empower everyone to contribute. Below is a breakdown of the ownership between Strategic Marketing and Pipe-to-Spend.

Website team

Digital Marketing Programs

Updating the Marketing Website

Naming conventions

Use consistent language across the site when naming links, page names, directory names, page titles, etc. If you see inconsistent language, log an issue to correct. We use american english on the site. Here are some examples below. If in doubt, ask in the #marketing slack channel for language help.

Do use nouns when appropriate

Do use the imperative tense as much as possible

Don't use noun forms of verbs

Don't use present participle ("ing" words)

Nouns may end in "ing"

Minimum Viable Change

Use MVCs to update the website. Create new pages and add the minimal amount of viable content. You can add images and more content in iterative steps.

We have 10-20 seconds to tell visitors why they should stay on our pages. Tell visitors what value the page will give them. Start with a high-level summary opening the page. This could be as simple as a single sentence, but we shouldn’t put the burden of discovering the value of the page on visitors.

The page title and URL should include keywords visitors might use to discover the page you’re creating. If you’re not sure what terms a visitor might use, ask the Digital Marketing Programs team for suggestions in your Merge Request. We have a list of high priority topics and recommended keywords to use.

Website Workflow

Here's a video that shows a typical workflow to update the website

Creating a new page

To create a new page you for follow these steps:

  1. Create an issue in the website repo Note: Don't branch from other repos like the marketing repo.
  2. Create an MR from the issue by clicking on the "Create Merge Request" button. This will create a new branch for you and link it to your issue and label the MR as WIP:.
  3. Click on the name of your branch after "Request to Merge" to open that branch in the repository file view.
  4. Open the source folder. This is where webpages are stored.
  5. Click on the directory where you want your webpage to be. For example, if you put a page in the source folder it will show up at the "root" level, if you create the new directory inside of another directory it will appear at that path.
  6. Click to add a New directory from the plus sign drop down.
  7. Name the directory in all lowercase with dashes-between-words for what you want the path of your page to be. For example if you want to create a page at about.gitlab.com/solutions/cloud-native then click on the solutions directory and inside the solutions directory create a new directory called cloud-native.
  8. Click to add a New file from the plus sign drop down
  9. Name the file index.html.md
  10. Add this code to the top of the file
---
layout: markdown_page
title: ""
---
## Subheading

Here is your first paragraph replace this text.
  1. Inside the quote add the title of your page. For example the title of my cloud native page would be "Building Cloud Native Applications With GitLab". Save your page by clicking "Commit changes". (Using markdown you can add more content to the page. All you need is a title, subheading and a paragraph to get started.)
  2. Return to the directory you created. You will see that you now have two files: index.html.md and .gitkeep. Delete the .gitkeep file. This is a placeholder file from when you created the directory since git cannot track empty directories. A quick way to delete the file on the correct branch is to click on "edit" in the changes tab of your MR. This will open the file editor. click "cancel" and dismiss the popup that says "all changes will be lost". This will then place you in the file view for the .gitkeep file on your branch. Click the "delete" button to delete the file.
  3. ProTip: Now that you no longer have a branch with no changes you can use the Web IDE to make further edits. (The Web IDE doesn't work if you have a branch with no changes. Fix coming in 11.3
  4. ProTip: Add a link to the bottom of your page so people can continue reading related content. Popular choices would be /product , /solutions, /pricing or any pages related to your page.
  5. If you need help you can Ping @williamchia in the MR or on slack in the #website channel.

@gl-website

If you are seeking assistance or need the attention of the website team, please include @gl-website in the issue description to ensure the website team sees it. The @gl-website handle is a group in GitLab that the website team uses to be notified of issues and merge requests from others. For community contributed merge requests, this happens automatically with gitlab-bot and you should see an automated message saying that the website site has been notified of your merge request.

Updating an existing page

  1. Click on the "edit" button at the bottom of the page.
  2. Edit the page. Note: page content can be in markdown, haml, or possibly in a separate .yml file that populates fields in the haml file. The hello bar is an example of content in a .yml file.
  3. If you need help you can Ping @gl-website in the MR or ping @website-team in the #website slack channel.

Moving a page

Great care should be taken whenever moving pages on the website. Ideally, pages should never be moved without implementing an immediate 301 redirect.

The Digital Marketing Programs team can follows this process to create 301 redirects.

Renaming a page

If you need to rename a page (e.g. change /company/culture/all-remote/part-remote to /company/culture/all-remote/hybrid-remote, as was achieved in this merge request), follow the below steps if using Web IDE.

  1. Within Web IDE, navigate to the directory that needs renamed, and click the option drop-down to select Rename.

  2. Rename the folder, then click Rename folder.

  3. Add a relevant commit message and submit a merge request.

  4. Within the newly created merge request, edit redirects.yml.

    1. To put the redirect in place, add a few lines to data/redirects.yml. Define "sources", "target", and "comp_op" like so:
   - sources:
   	 - /company/culture/all-remote/part-remote/
    	 - /company/culture/all-remote/part-remote
      target: /company/culture/all-remote/hybrid-remote/
      comp_op: '='

Optimize images

When adding an image to a webpage, be sure that you optimize the image first.

  1. Select the image you'd like to add to a page and save a copy to your computer.
  2. Add your local copy to ImageOptim and optimize the image for the web.

Updating the team page and org chart

  1. Both the team page and org chart are updated based on team.yml
  2. Edit team.yml and create an MR
  3. The org chart is built automatically based on slug and reports_to lines.
  4. See the team structure page for more info on specialties, expertise, and mentorship availability to a listing.

Updating the homepage promo banner (hello-bar)

Working with Stages, Groups, and Categories

Categories and stages are defined in the product handbook. Stages are stored in data/stages.yml and categories are stored in data/categories.yml as the single source of truth for engineering and marketing.

These two files power various parts of the website including the homepage, product pages, and product categories handbook.

They are also used by the automated triage operation "Stage and group labels inference from category labels".

Stage attributes

Below are attributes that can be added to a stage in data/stages.yml.

Category attributes

Below are attributes that can be added to a category in data/categories.yml.

Working with category maturity

There are five fields in categories.yml that control a category's maturity. These work together to define what the maturity currently is, how it has evolved over time, and our plans to improve in the future.

To change or update the current maturity, set the maturity field to the desired value: planned (or empty), minimal (available), viable, complete, and lovable. Next, ensure that the historical and future maturity values are still consistent. For example, if you incremented the maturity of the category from viable to complete, you should also set the field complete to the date of the GitLab release when it changed.

Sample template

authentication_and_authorization:
  name: "Authentication and Authorization"
  stage: manage
  alt_link: https://docs.gitlab.com/ee/administration/auth/
  documentation: https://docs.gitlab.com/ee/administration/auth/
  vision: https://gitlab.com/groups/gitlab-org/-/epics/628
  description: "GitLab features multiple auth mechanisms including LDAP (including Active Directory), OmniAuth, CAS, SAML, Okta, and Authentiq."
  roi: true
  available: 2017-10-01
  viable: 2019-05-22
  complete: 2019-12-22
  lovable:
  maturity: minimal

Proposing a change

Due to their importance and wide usage throughout the company, changes to Stages, Groups, and Categories need to be reviewed.

Major changes

Any change to a Stage or Group, or a significant change to a Category, is a major change. Examples of significant category changes include their names and their group membership.

Due to their impact, executive approval for major changes is required in addition to the PMs, PMMs, and EMs responsible. Follow the approval process defined on the categories page.

Minor changes

Minor changes to Categories are generally routine changes, like updates to maturity and content links. For example, upon shipping an MVC the maturity would change to minimal, and a link to the documentation would be added.

Approvals should be gathered from the responsible PMs, PMMs, and EMs. Also mention the relevant engineering and product directors, so they are aware of the changes. If changes are included in a release post, ensure the approval team and directors are mentioned on the MR.

Updating responsible persons for a Group

To update the responsible person for a role, follow these steps:

  1. Go to the GitLab.com / www-gitlab-com project
  2. Change the name of the responsible person in source/data/stages.yml at the relevant position e.g. pm: John Doe.
  3. Add the markdown reference link of the responsible person in source/includes/product/_categories.erb

Here's an example Merge Request.

If the person is not yet listed on the team page, please follow these instructions to add them.

Adding features to webpages

All features and capabilities are listed in a single yaml file (features.yml) under the features section. It is the single source of truth for multiple pages across the website including:

To add a new feature, add a feature block to under the features: section of the page. Add the following attributes:

For example:


- title: "Group Milestones"
  description: "Create and manage milestones across projects, to work towards a target date from the group level. View all the issues for the milestone you’re currently working on across multiple projects."
  link_description: "Learn more about Group Milestones"
  link: https://docs.gitlab.com/ee/user/project/milestones/
  screenshot_url: 'images/feature_page/screenshots/28-group-milestones.png'
  solution: plan
  category:
      - portfolio_management
  gitlab_core: true
  gitlab_starter: true
  gitlab_premium: true
  gitlab_ultimate: true
  gitlab_com: true
  github_com: false
  github_enterprise: false
  bitbucket_org: false
  bitbucket_data_center: false
  gogs: false
  jira:
    valid: true
    details: 'only through 3rd party extension'
  ca_agile_central: false

Copy and paste this template:


- title: ""
  description: ""
  link_description: ""
  link:
  screenshot_url: ''
  solution:
  category:
    -
  gitlab_core:
  gitlab_starter:
  gitlab_premium:
  gitlab_ultimate:
  gitlab_com:
  github_com:

Creating a DevOps tools comparison page

The /devops-tools section of the website shows info about DevOps tools and a feature comparison of those tools to Gitlab. Comparison pages are auto-generated from features.yml. All you need to do is add a tool to the devops_tools section and add that tool id to some features and the page will be created.

To add a new comparison page:

  1. Edit features.yml
  2. Under the devops_tools section add a tool.

Although the summary and include_file fields are not strictly required by the parser in order to build the page, every tool should have at least one paragraph summarizing the comparison using EITHER the summary field or the include_file field (see below for details). summary only is deprecated. Use include_file method whenever possible.

For example:

With include_file (preferred method):

  jenkins:
     name: 'Jenkins'
     logo: '/images/devops-tools/jenkins-logo.svg'
     category:
       - ci
       - cd
     include_file: devops-tools/jenkins/index.html.md.erb

With summary (deprecated method):

  chef:
     name: 'Chef'
     logo: '/images/devops-tools/chef.png'
     category:
       - infrastructure_configuration
     summary: |
       Chef is a configuration management tool that enables deployment and maintenance of state for large scale infrastructure. Chef excels as managing legacy infrastructure like physical servers and VMs. Chef was designed before widespread container adoption and does not implement Kubernetes natively.

       GitLab is a complete DevOps platform, delivered as a single application that includes not only configuration management, but also capabilities for project management, source code management, CI/CD, and monitoring. GitLab is designed for Kubernetes and cloud native applications.

       GitLab can be used together with Chef to enable VM and bare metal configuration management. For Cloud Native applications run on Kubernetes, Chef is not required and GitLab can provide all the functionality natively.

Copy and past this template:

unique_tool_id:
    name:
    logo: '/images/logos/TOOLNAME.png'
    category:
      -
    include_file: 'devops-tools/TOOLNAME/index.html.md'

  1. Add features to the comparison section.

Be sure to add features that GitLab has that the other tool doesn't and also features the other tool has that GitLab doesn't so that our comparison are transparent and honest (ie. this shouldn't be one sided).

For example:

  - title: "Free CI/CD with shared or personal Runners"
    capability: true
    description: "GitLab.com has shared Runners that allow you to use GitLab CI/CD completely free up to 2000 build minutes for private projects and unlimited for public projects. Alternatively, you can set up your own Runner for faster build processing, unlimited build minutes, or special requirements."
    link_description: "Explore GitLab.com offerings"
    link: /gitlab-com
    solution: gitlab_com
    gitlab_core: true
    gitlab_starter: true
    gitlab_premium: true
    gitlab_ultimate: true
    gitlab_com: true
    github_com: false
    bitbucket_org: 'partially'
    gitlab_ci: true
    codestar: false
  - title: "Domain Specific Language"
    description: "A Domain Specific Language (DSL) for defining infrastructure configuration allows thinking in resources, not files or commands to write declarative rather than procedural code."
    # link_description: ""
    # link: ''
    solution: missing
    gitlab_core: false
    gitlab_starter: false
    gitlab_premium: false
    gitlab_ultimate: false
    puppet: true
    chef: false

  1. If you followed the above step, the new comparison page should be reachable under /devops-tools/tool-vs-gitlab.html and you should see it on the devops-tools table on the main page.

  2. The last thing you need to do is create the PDF. Follow the info in creating comparison PDFs.

Adding content to resources

The /resources section of the website contains downloadable files and links to helpful content.

  1. To add a resource, edit the resources.yml file.
  2. To create a new entry for your resource, use this template and add it to the top of resources.yml:
- title:
  url:
  image: /images/resources/gitlab.png
  type: Pick one --> 'Blog post' 'One-pager' 'Report' 'Webcast' 'White paper'
  topics:
    - Cloud native
    - Code review
    - Continuous delivery
    - Continuous integration
    - DevOps
    - Git
    - GitLab
    - On-demand training
    - Public Sector
    - Security
    - Software development
  solutions:
    - Distributed teams
    - Accelerated delivery
    - Executive visibility
    - Project compliance
    - Security and quality
  1. Uploading a PDF: If the resource you'd like to add is a PDF, it can be uploaded to /pdfs/resources/.

  2. Selecting an image: Each resources has a thumbnail image based on their topic; select the most relevant image for the content. The current thumbnail images are shown below and can be found here. ALT

  3. Selecting a type: All resource types are listed in the code snippet above; select one that best fits your content. If the resource does not fit the current types, please see Requesting Website Updates to submit a proposal for new resource type(s).

  4. Selecting topics & solutions: The code snippet above provides all of the current topics and solutions; chose the topics and solutions that best apply to the content. Please note they are case sensitive and incorrect casing or spelling will result in the generation of new, unwanted, topics and/or solutions.

Requesting Website Updates

If you'd like to propose new changes to the website and the update is more complicated that you can do on your own to either create a new page or update and existing page you can request help from the Website team. New changes or updates with a due date should be requested at least 2 weeks prior to that due date.

  1. Before requesting help, create the content that you want to go live. E.g. draft the exact words that you want updated.
  2. To request help from the website team to update the site, create an issue in the www-gitlab-com project
  3. Add the specific content (exact wording and images) in the issue description that you want to put live on the website. Note: If the content is unclear, the issue will be assigned back to you to clarify the content before the website team will begin development work.
  4. add the Website label
  5. ping @gl-website in the MR or ping @website-team in the #website slack channel.