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 webiste, 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

Similiar 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

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.

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".
  2. Using markdown you can add more content to the page. All you need is a title, subheading and a paragraph to get started.
  3. 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.
  4. 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
  5. 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.
  6. 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.

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 comparison page

The /comparison 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/comparison/jenkins-logo.svg'
     category:
       - ci
       - cd
  include_file: devops-tools/jenkins/index.html.md
  chef:
     name: 'Chef'
     logo: '/images/logos/sdlc-competitors/chef.png'
     category:
       - infrastructure_configuration
     summary: |
       Chef is a configuration management tool that enables deployment and maintentce of state for large scale infrasstructure. 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 appliation for the whole DevOps lifecylce that includes not only configuration management, but also capabilities for proejct 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 Lanuage"
    description: "A Domain Specific Lanuage (DSL) for defining infrstructure configuration allows thinking in resources, not files or commands to write declarative rather then 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 /comparison/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.

  2. Add logos to the homepage and comparison page

    • Today still a manual process, but will be automated soon.
    • Add the name, logo, and url into sdlc.yml under the competitors ssecion for the corresponding "phase" (i.e. Stage).
    • Both pages pull from the same yml so adding it will cause it to show up in both places. For example:
- phase: Plan
...
  competitors:
    - name: Asana
      logo: /images/comparison/asana-logo.png
      link: /comparison/asana-vs-gitlab.html

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.