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

Product Communication

  1. You are here:
  2. Handbook
  3. Product
  4. Product Communication

Other Product Handbook pages

Communication

Internal and external evangelization

Before shipping a new or updated feature, you are responsible for championing it, both internally and externally. When something is released, the following teams need to be aware of it as they will all need to do something about it:

You can promote your work in several ways:

Working with Product Marketing (PMM)

Product marketers and managers should be joined at the hip. Just as a feature without documentation should not be considered shipped, benefits of GitLab that we're not actively talking about might as well not exist.

Product marketers rely on product managers to be guided to what is important and high impact. In general, you should:

Marketing materials

As a PM you're responsible for making sure changes you've shipped are well represented throughout GitLab's documentation and marketing materials. This means that on release, [features.yml][features] is updated, documentation is merged and deployed, and any existing content is updated where necessary.

It's not acceptable to do this after the release. GitLab is very complex, and features and functions are easily missed, even those that provide significant value to customers (e.g. the many ways you can authenticate with GitLab).

You can recruit the help of the marketing and technical writing team if needed, but it's highly recommended to do small updates yourself. This takes less time and overhead than communicating what needs to be done to someone else.

Major feature rollout

Major features deserve proper attention from Product and Marketing. With a proper rollout, we'll have ample marketing opportunities and receive more feedback ahead of, during, and after the release.

Here is the ideal rollout schedule. For each step there is an indication for who is responsible for it.

  1. Feature is drafted in an epic or issue (PM)
  2. Feature is planned in an upcoming release (PM)
  3. A feature proposal blog post is made (PM or Dev), which includes:
    • What we are planning on doing.
    • How people will be able to get it: CE or any EE Editions.
    • A link to the issue.
    • When it'll be available, if possible.
    • Anything else that is interesting to share in order to fuel the discussion.
  4. Feature is implemented, and documentation is written (Dev).
  5. Feature should appear on the website (Marketing)
    • For very significant features: Feature page on the website is made and pushed, with the mention "Available from X.X"
    • For other features: Feature should be listed on some page (/devops-tools, Enterprise page, /features page).
  6. Feature is launched with the release (Marketing)
    • "Available from X.X" is removed
    • Documentation and other resources are linked
    • Pricing page is updated if needed
  7. Feature is highlighted in a blog post (Marketing)
    • This post is linked from the feature page on the website (if applicable)

Release posts

As a PM, you are accountable for adding new features (under your umbrella) to the monthly release post, respecting the guidelines defined in the release posts handbook and its due dates. Be sure to go over all the details.

Every month, a PM will take the leadership of the release post, and will be responsible for delivering it in time.

Writing release blog posts

For every monthly release, there is a blog post announcing features. The blog post should contain everything exciting or disruptive. We want to help people understand exciting features (which are often new), and increase adoption. In general, release posts should succinctly state the problem to solve, the solution, and how customers benefit from the solution.

Some guidelines to help promote consistency of what is included in the blog post between different Product Managers are below.

Depending on the maturity level of your category should influence what you select for as a release post item.

It is recommended to start writing your release post items as a part of your Kickoff preparation. To reduce rework, use the headline of the release post as the issue or epic title. The description of the release post can simply be part of the description of the implementing issue. Writing the release post early and consistently enables you and your team to work backwards and have the following benefits:

Writing about features

As PMs we need to constantly write about the features and upgrades we ship: in a blog post, internally to promote something, and in emails sent to customers. There are some guidelines that one should take into account when writing about features, the most important being a clear communication of the problem we're solving for users.

When writing about a feature, make sure to cover these messaging guidelines which help produce clear internal and external messaging.

Let's highlight the messaging guidelines mentioned above with a concrete example, Preventing Secrets in your repositories, that we shipped in 8.12.

It's a bad idea to commit secrets (such as keys and certificates) to your repositories: they'll be cloned to the machines of anyone that has access to the repository. If just a single one is insecure, the information will be compromised. Unfortunately, it can happen quite easily. You write git commit -am 'quickfix' && git push and suddenly you've committed files that were meant to stay local!

GitLab now has a new push rule that will prevent commits with secrets from entering the repository.

Just check the checkbox in the repository settings, under push rules and GitLab will prevent common unsafe files such as .pem and .key from being committed.

Here are some additional examples of well written release blog posts for inspiration:

Recording videos to showcase features

In addition to the written medium, video is an important medium that caters to the different goals you are trying to accomplish and learning styles of your audience. Depending on the type of video you are recording, there are some guidelines to keep in mind.

As our documentation guidelines actively encourage linking video content, please consider following the Documentation Style Guide section on language, and working with your technical writing team to include links to your speed runs, walk-throughs and demos at relevant locations in the product documentation.

Speed Run

Speed runs are informal videos meant to focus on a single workflow and the experience for performing that workflow. It should not require much planning and is typically short in duration (less than 5 min.). This video type is meant to inform and not necessarily to influence buyers.

Examples:

Demo

Demos are scripted recordings meant to influence buyers. Generally has higher production value and typically involves both a slide-style presentation and/or live screen-sharing. Duration varies depending on the topics being covered.

Examples:

Walk-through

Product walk-throughs are informal videos meant primarily for an internal audience as a recorded, visual form of product critique. Walk-throughs typically focus on the user experience across categories and workflows within a Product Manager's product scope. There are particular benefits to walk-throughs which span product hierarchy boundaries (multi-category, multi-stage, multi-section) as they help highlight disjointed experiences across our single-application.

Walk-throughs are typically longer in length as they cover more ground and often involve some "live" troubleshooting and are best performed with no planning. Use the Product walk-through issue template when creating a walk-through.

Examples:

Including epics

One situation that can happen is that an epic contains many small issues that don't individually meet the bar for the direction label, and therefore inclusion in the release post. More rarely, the last issue of an MVC that took several releases isn't necessarily a capstone issue on its own. If you find yourself in a situation where you have closed an epic during a release, you should also ensure that we communicate that as a combined entity in a feature block, even if there is otherwise no single issue to mention.

Edit this page — open Web IDE — please contribute. Creative Commons License