Website Handbook

On this page

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 belogs 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

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 Product 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 Product Marketing and Pipe-to-Spend.

Product Marketing

Pipe-to-Spend

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 Online Growth 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 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 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 or @jareko in the MR or on slack in the #website channel.

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 following instructions are a stop-gap until marketing can gain the ability to self-sever 301 redirects.

  1. @mention @lbanks on your MR so that she can adjust paid campaigns to the new URL. WARNING: Do not merge without LJ's approval because it will break paid advertising.
  2. If the page has a form on it, @mention @jgragnola to adjust Marketo to know about the new URL. WARNING: Do not merge without Jackie's approve because it will break lead flow.
  3. Search for links to the old path and update all of the links to point to the new path.
    • Some code editors will let you search for a path.
    • Or use git grep to find all the of links for example git grep /team/
  4. Create a JS redirect.
    • create an index.html.haml file in the old directory
    • use this template replacing /path/ with the correct path:
     ---
     layout: blank
     title: Redirecting
     canonical_path: "/path/"
     ---
    
     - path = current_page.data.canonical_path
    
     %p{ :style => "text-align: center; margin-top: 30px;" }
       Redirecting to
       %a{ href: "#{path}" } https://about.gitlab.com#{path}
    
     :javascript
       window.location.replace("#{path}" + window.location.hash + document.location.search)
    
  5. Create an issue in the Infrastructure tracker to create a 301 redirect for the page.
    • Label it with oncall.
    • In the #production slack channel run the !oncall production slack command to see who is on call.
    • @mention the oncall SREs with a link to the issue and ask who can pick it up.
  6. Once the 301 is in place and tested, remove the JS redirect by deleting the index.html.haml page with the JS redirect.

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)

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: false
  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 competitors 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 competitors 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.

For example:

  jenkins:
     name: 'Jenkins'
     logo: '/images/devops-tools/jenkins-logo.svg'
     category:
       - ci
       - cd
  include_file: devops-tools/jenkins/index.html.md
  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 single application for the whole DevOps lifecycle 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/'
    category:
      -
    summary: |


  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.

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 in the dropdown menu. 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 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.