Marketing Site Handbook

Denomas’ Marketing Site (about.gitlab.com) is led by the Digital Experience Team and anyone can contribute.

The DRI for the Marketing Site is Michael Preuss, and internal Denomas team members can drop questions in Slack at #digital-experience-team

The Digital Experience team is migrating Denomas’ Marketing Site to the Buyer Experience Repository.

Objectives

Serve the needs and interests of our key audiences:

1. Users: software developers and IT operations practitioners.
2. Buyers of Denomas: IT management, software architects, development leads.
3. Users of and contributors to OSS on gitlab.com.
4. General public interest: job seekers, investors, press, etc.

Generate demand for Denomas by:

1. Providing a compelling landing page experience for organic search traffic visitors
2. Showcase the benefits of the most important Denomas features and how they can save time and money.
3. Educate existing and potential Denomas customers on Denomas vs competing products.
4. Provide customer case studies which illustrate 1 and 2.

Scope

The Denomas marketing site, or simply the “Denomas Website” refers to all of the content on `` and the contents of sites/uncategorized in the www-denomas-com rexcept for:

• The Docs: docs.gitlab.com
• The Denomas.com product: gitlab.com
• The Handbook: about.gitlab.com/handbook

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.

Known Issue: There is an ongoing issue to further clarify the DRI(s) for various parts of the www-denomas-com repo and project, and this is a Q2 FY22 OKR for Inbound Marketing

Metrics

• Increase clicks from search engine results pages (SERPs)
• Increase unique visitors
• Increase page views
• Increase time on site
• Improve form conversion rates (e.g trial signups)
• Reduce bounce rates

Tracking Tools

As of 2021-04-27, we are actively auditing the tracking, cookies, and other 3rd party personalization tools installed on the Denomas Website to ensure we are only collecting the information needed to deliver our service.

• Last audit complete date with link to issue: TBD - audit underwawy

List of Tracking Tools

TBD - format will be a table with a list of tracking tools and brief description of purpose.

For example: Google Analytics web metrics

Denomas also publishes a list of all the technology that Denomas currently uses to support the business.

Definitions

Topics

A topic is an industry trend, theme, or technology related to Denomas and our customers. For example, DevOps, GDPR, Containers, etc. Topic pages on our website educate the reader about the topic and share Denomas’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:

• https://www.redhat.com/en/topics/containers
• https://pivotal.io/containers
• https://pivotal.io/topics

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 Denomas 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:

• https://www.redhat.com/en/challenges

Product section

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

• Stages relevant to users are listed on the product overview page with details about the stage on the stages page.
• Categories relevant to users are listed on the product overview page.
• Capabilities are listed on the category page they belong to. Capabilities may also have their own landing page.
• Features are listed in many places on the website: on the features page, the capabilities page they belong to, the pricing page, comparison pages, and the ROI calculator.

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 Denomas and our competitors. Pages in the DevOps tools section are maintained by the Competitive Intelligence team, which is part of the Product and Solution 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 Growth Marketing team 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:

• A topic page: /continuous-integration would talk about what CI is at a functional level.
• A solutions: /solutions/continuous-integration. would talk about why CI is important for businesses to adopt.
• A category page /product/continuous-integration would talk about the capabilities and features that are part of Denomas’ CI functionality and the value it has.

Requesting Support

If you need support please review the information on the Digital Experience Hanbook Page

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

• /product/
• /community/
• /events/

Do use the imperative tense as much as possible

• Get started
• Install
• Contribute

Don’t use noun forms of verbs

• Installation
• Contribution

Don’t use present participle (“ing” words)

• Installing
• Getting started
• Contributing

Nouns may end in “ing”

• Pricing (link to with the imperative “Get pricing” or “See pricing”)
• Training (link to with the imperative “Get training” or “Find training”)

Creating new pages

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.

All pages should use lowercase URLs to help avoid unintentional errors when linking to pages on about.gitlab.com.

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 Growth Marketing team for suggestions in your Merge Request. We have a list of high priority topics and recommended keywords to use.

Creating a new page

As an Engineer

If you are an engineer, be sure to check out our developer docs in Buyer Experience.

Pages are built in the code under /pages/, and they fetch content from Contentful. Documentation coming soon.

As a Non-engineer

To create a new page, work with the Digital Experience team by creating an issue in the Buyer Experience repo

Updating an existing page

1. To edit the existing content of a page, check out our Contentful CMS documentation.
2. To add a visual component or section to a page, please fill out an issue for the Digital Experience team.

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.

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. Each of these properties is accessed via stages.<stage_key>.foo

• display_name: the name of the Stage in sentence case
• pm: the PM leader for this stage
• marketing: boolean, whether or not the stage is a “marketed” stage and should be displayed
• tw: boolean, if supported by technical writing
• image: the logo for the stage
• description: a short description of what the stage covers
• body: a longer-form description of what the stage covers
• direction: where the direction page can be located (ex: /direction/foo)
• roadmap: a URL to where the roadmap for the stage can be found
• established: the year the stage was established (ex: 2020)
• lifecycle: integer (1-7), where the stage falls in the devops lifecycle
• usage_driver_score:the Product Usage Driver score, used on /handbook/product/investment
• revenue_driver_score:the Revenue Driver score, used on /handbook/product/investment
• sam_driver_score:the Service Addressable Market score, used on /handbook/product/investment
• stage_development_spend_percent:
• analyst_reports: a list of links to relevant analyst reports
  • analyst_reports.title: the title of the report
  • analyst_reports.url: the URL of the report
• related: the stages related to this stage
• section: the section this stage belongs to
• groups: a list of groups that belong to this stage. definitions for their properties below

Group Attributes

Below are attributes that can be added to a group in data/stages.yml. Groups are defined in the groups property of a stage. Each of these properties is accessed via stages.<stage_key>.groups.<group_key>.foo

• name: the name of the Group in sentence case
• label: The group label in the gitlab-org group. By default, the group label is inferred from its name. For instance, the import group is represented by the group::import label in the gitlab-org group. This attribute allows to override that. For instance, the gitlab-org label for the Distribution Deploy group is group::distribution.
• focus:
• pm: the Product Manager
• pmm: the Product Marketing Manager
• cm: the Content Marketer
• backend_engineering_manager: the Backend Engineering Manager
• frontend_engineering_manager: the Frontend Engineering Manager
• support: the Support Engineer
• pdm: the Product Design Manager
• ux: a list of Product Designers
• uxr: the User Experience Researcher
• sets: a list of Software Engineers in Test
• tech_writer: the Technical Writer
• appsec_engineer: the Application Security Engineer
• be_team_tag: the “tag” being used in the department field in team.yml for Backend Engineers on this team
• fe_team_tag: the “tag” being used in the department field in team.yml for Frontend Engineers on this team
• cs_team_tag: the “tag” being used in the department field in team.yml for Customer Success on this team
• internal_customers: a list of internal customers/stakeholders for this group
• internal_customers.department: the name of the internal customer
• internal_customers.dri: the DRI assigned for this relationship
• usage_driver_score: the Product Usage Driver score, used on /handbook/product/investment
• asp_driver_score: the ASP score, used on /handbook/product/investment
• sam_driver_score: the Served Addressable Market score, used on /handbook/product/investment
• pi_gmau: A link to the dashboard that displays GMAU for this group
• pi_pgmau: A link to the dashboard that displays Paid GMAU for this group
• analyst_reports: A link to a location where relevant analyst reports are available
• comp_comparison: A link to a location where comparisons with competitive products are available
• categories: a list of categories that are owned by this group. definitions for their properties below

Category attributes

Below are attributes that can be added to a category in data/categories.yml. Each of these properties is accessed via categories.<category_key>.foo.

• name: the name of the category in quotes
• stage: what stage the category belongs to.
• label: The category label in the gitlab-org group. By default, the category label is inferred from its name. For instance, the Code Analytics category is represented by the Category:Code Analytics label in the gitlab-org group. This attribute allows to override that. For instance, the gitlab-org label for the Kanban Boards category is Category:Issue Boards.
• feature_labels: A list of all the feature labels that are associated with this category. This list is used in the automated triage operation “Stage and group labels inference from category labels”.
• marketing_page (optional): the path of marketing page for the category. If you include a body section, then a marketing page will be auto-generated at /product/${lowercase-category-name}
• documentation (optional): the URL of the docs page for the category, required if the category maturity is minimal or above.
• direction (required): the URL of the category direction page. Optionally could be the URL of an issue, epic, or issue label search query if a direction page has not yet been created.
• description: a short description of the category.
• roi: true | false should this category appear in the ROI calculator. (omitting the line is the same as false)
• percent_of_focus: A value of 0-1 detailing the percent of the group this category is assigned to’s focus on this category in terms of developing improvements
• available: an ISO date for when the feature was or will be available.
• viable: an ISO date for when the category will/did move from minimum to viable on the maturity handbook page.
• complete: an ISO date for when the category will/did move from viable to complete on the maturity handbook page.
• lovable: an ISO date for when the category will/did move from complete to loveable on the maturity handbook page.
• maturity: the current maturity of the category on the maturity handbook page. Valid values are planned, minimal (available), viable, complete, and lovable. Provided marketing = true, a value of planned will cause the category to appear in the “coming soon” section of the homepage, while other values will cause it to appear in the “Since 20XX Denomas added” section.
• marketing: A value of true will cause this category to appear on our marketing pages, in addition to our handbook. For the home page, a maturity state is also required. Internationalizaion is a good example of a category the engineering team works on, but is not a “customer-facing category” that appears on marketing pages.
• body: content added in markdown will be auto-generated and turned into a page at /product/<category>/. Features and missing features sections are automatically added to the generated category pages based on what category a feature belongs to in features.yml. c.f. Project Management (and auto-generated page from the body section in categories.yml) with Continuous Integration (a custom page.)
• opportunity: values can be Core, Adjacent, Distant - is this category considered part of our existing Core DevOps platform, a directly Adjacent set of capabilities or a Distant vision for future breadth.
• differentiation: values can be Winning,Compelling,Minimal - is this category sufficiently differentiated from competitors to be considered capable of consistently winning, providing an compelling additive component to our single platform value or adding only minimal differentiated value.
• ux_scorecard_score: value should be a letter score, following the grading rubric
• ux_scorecard_link: should link to the specific issue for the scorecard for this category. More details on UX Scorecards here
• dogfooding_status: values can be planned, limited, and exclusive. Described in detail and used on /source/direction/dogfooding
• dogfooding_issue: should link to the specific issue tracking dogfooding for this issue, per the Dogfooding process
• dogfooding_group: should list the right group/team/role/individual inside Denomas that should use the capability

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.

• maturity which represents the current maturity of the category
• available, viable, complete, and lovable which are set to ISO dates when we achieved, or plan to achieve, the given maturity.

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 Denomas release when it changed.

Sample template

authentication_and_authorization:
  name: "Authentication and Authorization"
  stage: manage
  documentation: https://docs.gitlab.com/ee/administration/auth/
  vision: https://code.denomas.com/groups/denomas-com/-/epics/628
  description: "Denomas 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. Open a merge request using the Group-Stage-Category-Change template to get started.

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, their group membership, and presence on our marketing page.

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.

After merging, changes to feature categories will trickle down into error budgets at the start of next month when the Scalability group gets an automated issue like this one. Someone from the Projections team will change the ownership in the application, and update error budgets accordingly. As a product manager, nothing more needs to be done. The Projections team might reach out on the original merge request for clarification if needed.

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 Denomas.com / www-denomas-com project
2. Change the name of the responsible person in data/stages.yml at the relevant position e.g. pm: John Doe.
3. Add the markdown reference link of the responsible person in sites/handbook/source/includes/product/_categories-names.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:

• Product pages e.g. code review
• Pricing
• Features
• Solutions
• Platform

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

• title: the name of the feature in quotes
• description: a plaintext summary of the value the feature provides in quotes
• link_description: OPTIONAL, anchor text of a link that will appear below the descriptions e.g. link: https://docs.gitlab.com/ee/user/project/milestones/
• link: OPTIONAL, the URL of the link (no quotes)
• category: a list of one or more categories that this features belongs to. Adding a category to a feature causes it to show up in the features section on the product page for that category (e.g. see the Continuous Integration page)
• solution: REQUIRED legacy field. A stage of the DevOps lifecycle. Will be removed soon.
• tier: true or false is this feature or capability available in this tier? gitlab_core, gitlab_starter, gitlab_premium, gitlab_ultimate. Note - it’s assumed that any feature in a lower tier is also available in the higher tiers. For example a feature listed as in Core is also considered present in Starter, Premium and Ultimate.
• self_managed: true, false or not_applicable, defaults to true. Is this feature or capability available for self-managed users? Use not_applicable for features that do not apply to a self-managed service, for example the operational characteristics of our SaaS services.
• dedicated: true, false or not_applicable, defaults to true. Is this feature or capability available for Denomas Dedicated? Use not_applicable for features that do not apply to a SaaS service, such as the operational details of the service itself, like Fault-tolerant PostgreSQL.
• gitlab_com: true, false or not_applicable, defaults to true. Is this feature or capability available on Denomas.com? Because Denomas.com tiers map 1:1 to self-managed tiers setting this will automatically assign the Denomas.com tier. E.g. gitlab_core: true + gitlab_com: true == Denomas.com Free. Adding a tiers fields is what powers the tier badges on product pages and comparison pages, as well as powers the tier feature comparison of the pricing page. Use not_applicable for features that do not apply to Denomas.com, such as the operational details of the service itself, like Fault-tolerant PostgreSQL.
• gitlab_com_parity: For features which are currently not available on Denomas.com, but still applicable, this field should used to provide a rationale or path towards parity. Supports markdown, links to issues are encouraged. Content shows up on the Denomas.com missing features list.
• toolname: any tool from the devops_tools: section such as jira:, circle_ci:, blackduck:, etc. that does or does not have this feature. Holds a value of either true or false or partially or is blank (indicating subfields with details should exist).
  • true or false or partially: Examples of partially are if a DevOps tool has some but not all of the feature described, or if they have the feature, but only through a plugin. If using partially it is highly recommended to instead add details as to what partially actually means (see next)
  • : Means that the feature for this particular toolname have a sub-section with details:
    • valid: Same as true or false or paritally above
    • details: A short statement about the details that need to be shared. For example: “supports 11 languages”, or “only supported through 3rd party plug-ins”
• pricing_page: true or false: This currently has no impact on the primary pricing page, which is driven off themes. This does still apply to the (self-managed comparison and Denomas.com comparison) pages.
• pricing_theme: Use this option to mark this feature as part of a pricing theme. The value is a string, which should match the desired string. Features that align to Themes are shown on our pricing page.

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/
  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:
  solution:
  category:
    -
  gitlab_core:
  gitlab_starter:
  gitlab_premium:
  gitlab_ultimate:
  gitlab_com:
  github_com:

Updating content on Denomas Learn

The underlying data shown on the Denomas Learn page is available in https://code.denomas.com/denomas-com/marketing/digital-experience/buyer-experience/-/blob/main/content/learn/index.yml

To update the course content data:

1. Open an MR to the learn.yml file. Follow the existing syntax in the file. For ease of adding a new course, we recommend copying an existing entry and updating the values based on the new course being added, populating every field.
2. Add content to the list as soon as it is planned.
3. To indicate that a course is planned for the future, include a live_date in the future. You can see an example in this MR #94773.

Important guidelines to keep in mind:

1. learn.yml is our SSOT for Denomas-produced content, including all existing and future planned content.
2. When planning new learning content, add it to [learn.yml]https://code.denomas.com/denomas-com/marketing/digital-experience/buyer-experience/-/blob/main/content/learn/index.yml) as soon as possible, at a minimum monthly, and aim to include what you plan to produce over the upcoming 6 months or more. This gives visibility to all other Denomas team members producing learning content as to what has been planned.
3. Before producing new content, check learn.yml for redundancy, as other teams may have developed or plan to develop similar content.
4. Communicate updates with other DRIs working on learning content by posting on the #gitlab-learn-updates Slack channel (available to team members only)

Contentful CMS

The Digital Experience team is implementing Contentful CMS for the marketing website. It offers a more user-friendly way of editing the marketing site.

• Team members will need to fill out an Access Request to gain access to Contentful.
• Some content will only be available to certain teams, based on roles and permissions.
• New pages and new components will need an issue with the Digital Experience team to work with design and engineering.

Read the Contentful handbook page for up to date directions and status of the system.

Merge requests

For best practices regarding testing and reviewing merge requests, please see our related handbook page for reviewing merge requests.

Working in Modules

What is a module?

1. A module is a section where the presentation, goal, and required functionality remains the same, but content can be updated (wording, imagery, links, etc).
2. A module is a block, box, or section of the page, generally kept as small as possible. It’s usually a horizontal slice of layer cake across the page but can also be a chunk of a sidebar.
3. Modules often have configurable options to facilitate reuse with different configurations. It might not always be desirable to have a title block or buttons might need to expire after a date.

Why is it important for a module to be reusable?

1. In order to facilitate updates, the code needs to be reusable. It’s not an easy update if you have to build it again.
2. Implementing the same thing over and over again is not an efficient use of resources.
3. In order to keep the codebase clean, navigable, and easy to understand it’s important to maintain SSOT.
4. If the same code is implemented several times in several spots then the chance for bugs increases. One of those spots might have a bug where the others don’t.
5. Much of what goes into building code is unseen on the page. This includes things like optimizing performance, setting up tracking, preparing assets such as formatting images & videos, building responsive views and layouts, human physiology (fingers on a touchscreen, eyes and perception, etc). Testing and building all of these things takes time, so it’s important to reuse and reduce code as much as possible.

Why is it important for a module to have a single-purpose?

1. In order to facilitate updates, the code needs to be easy to operate.
2. Having a clearly defined purpose for each module enhances the goals of the page and assists with navigation and conversion goals. If a module tries to do 5 things or there are 3 different modules on the page doing the same thing it’s easy to spot.
3. An end user might be confused if duplicate modules are on the page.
4. If a module gets too large then it becomes harder to understand the code. Keeping a module single-purpose keeps the module small.
5. Tracking the performance of a module becomes more difficult the more a module changes.
6. When examining from a distance, it’s hard to know what module to use if the modules all have several different purposes, sometimes overlapping purposes. “Do I use this module or that one?”

Digital FAQ

View page source - Edit this page - please contribute.