Tools and tips

This page contains useful tips for working at Bramble and for various tools we use such as Slack, Zoom, and Google.

You can find more tools and tips in the following sub-pages:

• macOS page
• Linux page
• Other apps
• How to search like a pro
• git page
• rubocop page

Bramble tips

Linking Gravatar photo

Link your Bramble email address to an easily recognizable photo of yourself on Bramble, Slack, and Gravatar. It is company policy to use a photo, and not an avatar, a stock photo, or something with sunglasses for any of your Bramble accounts. Our brains are comfortable with recognizing people; let’s use them.

Resizing Images

ImageMagick provides the convert CLI command which can be used to resize images. Our blog images do not need resolutions higher than 1920x1080. This saves bandwidth and makes the website load faster.

On macOS, install ImageMagick with Homebrew:

$ brew install imagemagick

On Linux, use your package manager:

$ sudo dnf install ImageMagick
$ sudo apt install imagemagick

This example converts an existing image to 1920x1080 resolution and replaces it inline:

convert blogimage.jpg -resize 1920x1080 blogimage.jpg

You can also use percentage values for the -resize parameter. The convert CLI command can do more things explained in the documentation.

Using Mermaid

Mermaid is a tool that allows us to create flowcharts, graphs, diagrams, Gantt charts, etc. within GitLab! Check out the examples in the Learn Hugo Theme on how to use Mermaid.

A few additional resources that can be helpful when working with Mermaid are:

• The live mermaid editor to check your work!
• GitHub’s Mermaid overview
• A CSS color bank to add color to your charts.
• You can see an example of how to add images to Mermaid charts here.

Note: When creating Mermaid charts in the GitLab ok, you need to type three back tick symbols followed by the word mermaid before the chart, and three back tick symbols at the end of the chart. This will enable Markdown to distinguish between .md and Mermaid. Please reference the example Mermaid charts linked above to see how this looks live.

U2F

Universal 2nd Factor (U2F) is a cryptographically strong 2FA (2-factor authentication) method. It is hardware-based, and is typically deployed via a USB or NFC device. The standard is open and is maintained by the FIDO Alliance.

How it works

During the authentication process, you enter in your username and your password. On systems with 2FA enabled and using U2F, the hardware token is queried. By pressing a button or tapping a sensor on the U2F device, the U2F device completes the authentication process in a cryptographically strong way. It is generally considered the most secure form of 2FA. It is also more convenient than manually entering codes generated by a TOTP application.

During the registration of the U2F device, a public/private key pair is generated, with the public key being registered with the service you will be authenticating with, and the private key is stored on a secure chip in the U2F device. When authenticating, after you’ve entered in your username and password, the U2F is queried via an encrypted message that can only be authenticated by the private key, so a button or sensor is pressed on the U2F device to allow the query to be completed, and the user is then granted access to the system.

U2F devices

YubiKey: The most popular U2F device is Yubico’s YubiKey. There are a wide variety of sizes and styles of YubiKeys. Yubico (along with Google) helped develop the original U2F standard before it was moved to the FIDO Alliance. Most Bramble team members that have U2F devices have a YubiKey. It should be noted that for a long time Yubico’s source code for its firmware was open source, but some of the newer versions of firmware are closed source. This has caused some concern in the security community, particularly those that prefer to use open source whenever possible.

Solo Security Key: Solokeys' Solo Security Key is growing in popularity, and while it often lags behind in certain features, it is also used by a few Bramble team members with success. The company began as a Kickstarter project, both the hardware designs and firmware source code are open source for Solokeys, and the open source nature is the reason a number of team members favor it.

Are They Secure?

Both the YubiKey and the Solo have been examined by both the security industry at large, third party audits by both keys' companies, and by the Security Team. Either company’s offerings are more than suitable for use within Bramble and work fine with U2F-compatible systems.

YubiKey has had a number of security issues which are typically resolved quickly. They have a dedicated page for security advisories.

Solokeys has had a few security issues but as their website has no dedicated security advisories page one must either scan through their blog or read through the release notes on their source code repository.

In rare cases, a security issue involving a hardware token arises that requires the hardware token to be replaced as a firmware update will not mitigate the issue. This happened with Yubico in 2017.

Most of the attack models that impact the U2F tokens require physical access to the token itself. That is, the security advisories involve coding issues that can only be exploited via access to the token or the computer that the token is plugged into. This in itself makes the devices more secure.

Recommendations

Either device is fine for Bramble use, and there are other hardware tokens that are also decent (if you have questions, ask the Security Team in the #team-security Slack channel). The Security Team has looked at Yubico and Solokeys devices, and while both are secure, there are a few differences listed below one should keep in mind (current as of July 9, 2020):

• YubiKey offers GPG integration, Solo Security Key does not.
• Both products offer SSH integration, however Solo Security Key does not support ED25519.
• YubiKey allows for static password storage, Solo Security Key does not.

What Bramble team members need to keep in mind is that if you travel with your company laptop - either on a business trip, a trip to visit family and friends in another location but you intend to keep working, or just a trip to the local coffee shop - treat the U2F token with the same level of care as a credit card. Do not leave it where it could be stolen.

If you are concerned about potentially losing your U2F hardware token, you can always purchase a second one, register it, and store it at a secure location. Sites following the U2F standard should support multiple hardware tokens. That way if one is lost or stolen, you can still use the other token.

Usage of 2FA is mandatory for Bramble team members. While it is not mandatory to use a U2F hardware token at Bramble as your 2FA solution, it is highly recommended as it is one of the most secure and convenient ways to meet 2FA requirements.

Slack

Do Not Disturb Hours

Slack now supports “Do Not Disturb Hours” so you won’t be pinged in the middle of the night or while you are dealing with family matters. You can set your “Do Not Disturb Hours” by clicking on the bell at the top of the left pane in the Slack app. You also have the option of snoozing for 20 minutes or up to 24 hours. Note: Do Not Disturb can be overridden in the event of an emergency. See Slack documentation for more information.

Browse Channels

You can browse all available Bramble channels by clicking on “Channels” on the left pane in the Slack app. From there, you can see every channel, who created it, and how many members there are. Feel free to ask for recommendations from other team members for their favorite channels. Every team member is automatically added to the #company-fyi and #whats-happening-at-bramble channels, where announcements are made and information for the entire company is shared. There are also a few default channels that every new hire is added to, such as: #celebrations, #new-team-members, #questions, #random; these channels are optional, but we think they are a great place for team members to interact and get to know each other.

Organize Channels in Sidebar Sections

Slack now supports organizing channels in sections. Previously this only was possible through “Starred” channels. Navigate into the Slack preferences and select the Sidebar navigation item. Click on Create Section to create a new section on the left sidebar. You can also do that from the settings menu of each existing section.

Feel free to organize this with your most frequent used channels, or specific team grouping. You can drag and drop and also hide sections. You can for example create the info section and add #company-fyi and #whats-happening-at-bramble as channels. Additionally, add the team section and move all related channels there.

Channels Access

In addition to Bramble team-members, designated groups such as the Core Team members and advisors outside of Bramble may be granted access to our Slack channels. However, internal channels that start with #a_ will be restricted to Bramble team-members who have been invited to those channels only. Any confidential conversations regarding our customers should be restricted only to #a_ channels. The rationale for internal channels is that it could be a breach of many of our contracts for third parties to have knowledge of Bramble customers. This is especially the case when third parties could be customers' competitors.

Slack Status

Slack allows you to set your status for your fellow Bramble team members by using your choice of standard messages such as “Away” and “Lunch” or a custom message and your choice of emoji. If you’re off work for a holiday or vacation you can update your status by using PTO by Roots. This is a great way to let your team know whether you are available.

To have your Slack status automatically set to “In a meeting” based on your Google Calendar, add the Google Calendar app to your Slack account.

Invite

There are multiple ways to invite people into a Slack channel. The easiest way is to use the invite command by typing /invite @jenny. Avoid inviting people through a mention message. E.g. @jenny as it can create a message that distracts others.

Quick Switcher

Quick Switcher is a great feature to know about if you want to get productive with Slack. As the name suggests, it allows you to switch between channels and direct messages quickly. Invoke it with Cmd + k on Mac or Ctrl + k on Windows or Linux and start typing the name of the person to chat with or the channel you are interested in. You can then navigate the suggestions with ↑ and ↓ keys and hit enter to select.

Display only unread conversations

With lots of channels and direct messages, Slack can become overwhelming. To help keep track of activity on Slack, and to simplify the interface, consider displaying only unread conversations.

Minimize Visual Distractions

Animated images and emoji can add meaning to conversation, but they can also be distracting. If you would prefer to have static images and emoji, disable the animation. For details, see Manage animated images and emoji.

Sort channels and direct messages with stars

To sort direct messages and channels, open the direct message or channel and click on the star icon. For details, see Star channel or direct message.

Unfurling Links in Messages

Slack has a built-in feature to Unfurl links included in messages posted to Slack. This will post a preview of the link alongside the message. You can remove the unfurled preview of the link by hitting the “x” in the top-left of the preview. This will then prompt you to confirm removing the attachment, which you can hit “Yes, remove”.

In the confirmation prompt you may also see a checkbox to “Disable future attachments from this website”. As a workspace admin if you select the disable option this will denylist the link/domain across the workspace and will impact every user. If you do happen to denylist a link or a domain, they can be modified in the Workspace admin portal under Settings & Permissions.

Change Group DMs to Private Channels

If you are in a group direct message with multiple people, you can change it to a private channel, in order to avoid extra pings and allow additional team members to be added or removed to the channel.

Custom theme

The interface colors can be customized in Slack. This is especially useful when using multiple slack accounts, setting up different themes makes it really easy to differentiate them instantly. The theme selector is available under Preferences > Themes.

In order to setup a Bramble theme, send yourself the following message: #643685,#634489,#FC6D26,#ffffff,#71558f,#ffffff,#FCA326,#e24329, and press the Switch sidebar theme button.

Slack Apps

Many applications can integrate with Slack.

Recommended apps:

1. Google Calendar - By integrating your calendar with Slack, you’ll get notifications about meetings directly in Slack. Most important - 1 minute before a meeting begins, you’ll receive a message with the meeting info, including a link to join meetings that are occurring in Zoom. You can set up the integration by typing /gcal into any message field.

Slack Reminders

Slack reminders help you to remember things without having to keep it all in your head. You can set reminders for yourself or other team members. You will receive a notification at the specified time.

You can use natural language with the /remind command. Type /remind help to get some tips. For full information on Slack reminders see the Slack help.

Zoom

There is a lot of information pertaining to Zoom, as it is a critical part of Bramble’s communication. See the Zoom ok page.

Tip: The [Google Calendar](/handbook/tools-and-tips/#google-calendar) invite is the single source of truth for the Zoom link. Avoid linking the Zoom link in Google Document agendas since those may quickly become out of date. If the zoom link changed around the start of the meeting it is OK to have it in there temporarily.

Google Docs

Google Docs Pro Tips

1. Quickly create a new Google Doc in chrome: type “docs.new” in the chrome address bar. Likewise “sheets.new” for a Google Sheet etc…
2. While in a document with many other editors, click on the image or icon of any user at the top of the document to move focus to their cursor and what they are typing in the document. This is great when someone is speaking about something they are typing on a video call and you are not sure where they are in the document.
3. Quickly find all action items assigned to you with a search for followup:actionitems.
4. During meetings, in the upper-right side of the window for a Google document, double-click on the picture (or first initial) of the person speaking to see where their cursor currently is in the document being discussed.
5. To add additional rows to a numbered list in a Google Document, press Return to add additional spaces under the existing numbered list in the document, highlight those spaces, and click the numbered list icon in the formatting bar (or press Command ⌘ + Shift + 7 on a Mac) to create a numbered list from the spaces. See video on how to add more rows to a numbered list for a quick tutorial.

See also Live Doc Meetings for more Google Doc tips.

Google Analytics

Google Analytics (GA) is an essential tool for making data-driven decisions.

Read through the Inbound Marketing Handbook for more information on GA.

For example, you can look at the GA data to analyze how visited is a certain page, in a period of your choice. You can also look at the GA referrals data to understand where the users are coming from and where they go when they leave a certain page.

To see the data for a specific page:

• Open GA, and expand Behavior on the sidebar

• Click Site content > All pages

• On the top-right, adjust the period of time you’d like to analyze

• On the middle of the page, look for a search bar and paste the URL you’d like to analyze (without https://) and click on the magnifier button to search:

  

  Note that you can use the search tool with:

  • A full URL, which will return results for that specific URL
  • Part of an URL, e.g., /2017/, which will return the results for all the blog posts published on 2017
  • The higher directory on the file tree, which will return the results for a range of URLs in that tree. E.g., docs.gitlab.com/ee/ci/ will return the results for all the range of pages contained in the /ci/ directory

• GA will output the data about the page (or range of pages) you searched for, including pageviews, unique pageviews, and other data:

  

To find the referrals for a certain page, continue from the steps above.

• Click on one of the website links to look at the data for a page of your choice

  

• Just above the graph, click Navigation summary

• GA will output the referrals, including Previous Page Path and Next Page Path:

  

Set your picture in Google

Optional: Set your picture in Google so that your picture will show where you are in a Google document (vs showing just your first intial). This will allow others to more easily follow a discussion when meeting attendees move around in a document.

Google Calendar

Finding a time

Please make use of the Find a Time tab in Google Calendar, especially when scheduling events with teammates in other parts of the world:

Find a Time presents a new or existing event’s time for all participants, adjusting for time zones as appropriate. To use Find a Time:

1. Create a new event or modify an existing event.
2. Click the “Find a Time” tab. Invited guests will be presented in the availability table and represented by a column.
   • Areas outside of someone’s working hours (9:00 AM - 5:00 PM by default) are represented in light grey.
   • Guests who are optional will not appear in the availability table by default. You can add them by checking their name in the “Guests” area on the right hand side.

Bramble Availability Calendar

Please please subscribe to and use this OOO calendar: https://calendar.google.com/calendar/u/0?cid=Y19kaWJiN2RsZWt2cDMwcmQ4YzkwanZwYzcyb0Bncm91cC5jYWxlbmRhci5nb29nbGUuY29t

Remember - create an Event with the OOO Calendar, NOT an Out of Office in your own calendar

Bramble Team Meetings Calendar

The Bramble Team Meetings Calendar is available to all team members and can be found in your calendars list. You can find the details for the Company Calls, Group Conversations, 101s, and other teams' meetings here, so you can attend a different team’s meeting and ask questions, learn about what they’re working on, and get to know the rest of the Bramble Departments and teams. These meetings are open to everyone in Bramble. If you are creating a new team meeting, please copy it to the Bramble Team Meetings calendar, and reach out to the People Experience team by pinging @people_exp in the #peopleops Slack channel with any questions or requests. Please reach out to the People Experience team for any requests and changes to the Bramble Team Meetings calendar.

To add an event to this calendar:

1. Create your calendar invite.
2. Add your zoom link.
3. Add agenda.
4. Under Add Guests, add GitLab Team Meetings

Managing invite responses

Add a filter to remove invites responses from your inbox with the following query:

*.ics subject:("invitation" OR "accepted" OR "rejected" OR "updated" OR "canceled event" OR "declined") when where calendar who organizer

Modifying Events

Please click ‘Guests can modify event’ so people can update the time in the calendar instead of having to reach out via other channels. You can configure this to be checked by default under Event Settings.)

Restore Deleted Calendar Items

(This assumes you are using Google’s new Calendar).

When you have accidentally deleted something from the Team Meetings calendar, you can recover it by:

• Go to Google Calendar and click the gear icon at the top left of your screen.
• Choose the Trash.
• Make sure you are on the correct calendar, by clicking on the name of the calendar in the left sidebar.
• Hover over the item you’d like to restore and click the arrow to “Restore”.

Sharing

We recommend you set your Google Calendar access permissions to ‘Make available for Bramble - See all event details’. Team member calendars should not have access permissions set to ‘Make available to public’ due to the risk of sensitive data exposure and zoombombing.

Consider marking the following appointments as ‘Private’:

• Personal appointments
• Confidential & sensitive meetings with third-parties outside of Bramble
• 1-1 performance or evaluation meetings
• Meetings on organizational changes

There are several benefits and reasons to sharing your calendar with everyone at Bramble:

1. Transparency is one of our values and sharing what you work on is in line with our message of “be open about as many things as possible”.
2. Due to our timezone differences, there are small windows of time when our availabilities overlap. If other members need to schedule a new meeting, seeing the details of recurring meetings (such as 1-1s) will allow for more flexibility in scheduling without needing to wait for a confirmation from the team member. This speaks to our value to be more efficient.

If you’d like to share your calendar with e.g. your partner you can use the ‘Share with specific people’ feature and set the permissions to ‘See only free/busy (hide details)':

Speedy Meetings

Enable speedy meetings to automatically provide a buffer at the end of events you schedule. This thoughtfully allows participants with back-to-back events the opportunity to use the restroom or grab a cup of coffee without being late to their next function.

World Clock

Add as many time zone world clock as you wish by going to Settings -> World Clock.

Google Drive

First, an important message - Don’t use Google Drive/Apps (unless you have to)

We would be remiss if we didn’t start this section off with this IMPORTANT message: Your default storage place for information that needs to persist and be available to others in the company should be ON THE WEBSITE/IN THE COMPANY HANDBOOK and not in Google Drive and Google Apps files!! This is from the top. This is how we operate, because Google Docs/Apps can only be found and contributed to by team members, and not by users, customers, advocates, future employees, Google ok searches, or developers.

Which files and rules to using Google Drive/Apps

Having said that, there is content which doesn’t make sense to be created on the website directly (e.g. large collections of data in tables, spreadsheets for calculations, etc) or for which Google Drive storage makes sense. For these, when creating or storing files in Google Drive, the web/handbook should have a link to this content and effectively be the index for finding things of relevance that are stored in the Google drive.

There are a few ways to do this to maintain proper levels of privacy:

Link from ok but view for Bramble only

Rarely, but sometimes, it is appropriate to store files in Google Drive but NOT let those outside Bramble see it. In general, this is when there is information which we need to keep, but which we are under obligation to not share. Examples of this are:

• Any work with partner, customer, or investor information which we have not been cleared to share
• Analyst reports and related information that are not redistributable
• Customer interview videos which have not been approved for distribution

Link from ok, everybody view, but Bramble edit only

Everything else should be viewable by the public, although not necessarily editable by them. Examples of this content are:

• Meeting notes
• WIP mockups/graphics

Following are some tips for how to use Google Drive for the instances where it makes sense to.

Keeping it organized

It is important that we not just throw files into random or general places in the shared Google Drives. Doing so makes it harder for others to find and work with the content. Here are some guidelines to organizing the Google Drive content:

• First by department (e.g. strategic marketing)
• then by subject (e.g. analysts relations)
• then by sub-subjects as deep as necessary (e.g. Gartner -> 2018 ARO MQ)

Using Google Drive

For starters, when your Bramble Google company account is created you automatically get a Google Drive with unlimited storage allocation in your own “home” directory (called My Drive). You can get to it by:

1. (optional) Login to your Bramble account in your browser (if you are using Chrome)
2. Open your web browser to https://drive.google.com
3. If you’re not already logged in as your Bramble account (Chrome users should be) then login to Google using your Bramble account
4. This will take you to your Google Drive (called My Drive) which is like your home directory. If you create Google files using Google Apps and don’t specify where to store them, they will be put in this home directory.

This is great for storing your own working files. As already stated, this should never be the final resting place for shared files that are meant to be used by the rest of the company (or beyond).

Google Mail (Gmail)

Auto-advance

If you use the archive function, you normally return to your overview. With Auto-advance you can select whether to advance to the next or previous message. “Auto-advance” can be enabled from the Advanced section under Settings. This reveals the Auto-advance settings in the General section under Settings. The default setting of showing the previous (older) message is usually preferred.

Email signature

Set up an email signature which includes your full name and job title so people can quickly know what you do.

Example

Note: You can copy and paste the template below to use it in your own signature.

John Doe Frontend Engineer | Bramble

Filters

Apply label on mention

It might be useful to add a Gmail filter that adds a label to any GitLab notification email in which you are specifically mentioned, as opposed to a notification that you received simply because you were subscribed to the issue or merge request.

1. Search for from:(gitlab@mg.gitlab.com) "you+have+been+mentioned+on".
2. Click the down arrow on the right side of the search field.
3. Click Create filter with this search.
4. Check Apply the label: and select a label to add, or create a new one, such as “Mentioned”.
5. Check Also apply filter to matching conversations.
6. Click Create filter.

Apply label to all GitLab-generated emails

GitLab issues and merge requests can generate a lot of email notifications depending on your settings and how in-demand your attention is. It can be useful to apply a label to these generated emails and move them out of your immediate inbox.

1. Search for from:gitlab@mg.gitlab.com.
2. Click the down arrow on the right side of the search field.
3. Click Create filter with this search.
4. Check Skip the Inbox (Archive it).
5. Check Apply the label: and select a label to add, or create a new one, such as “GitLab.com”.
6. Check Also apply filter to matching conversations.
7. Click Create filter.

You can learn more about how to use Gmail filters to organize your inbox in Productivity Hack video. To import downloaded filter export go to Gmail => Settings => Filters and Blocked Addresses => Import filters.

Keyboard shortcuts

Keyboard shortcuts only work if you’ve turned them on in Gmail Settings.

Steps below:

• In “Settings” scroll down to the “Keyboard shortcuts” section
• Turn Keyboard shortcuts “on”
• Scroll down and Save Changes

Here are some shortcuts you can use

Split screen

List your inbox and preview mails in one view with this configuration change:

• Cog/settings top right of inbox.
• Settings option.
• Inbox tab
• Reading pane: enable
• Select a position for the reading pane, Right of Inbox or Below Inbox
• Save changes
• Reload inbox

Travelling

Long haul flights

Note: you have to pay for these items yourself.

• Quiet comfort 35 Bose over ear noise canceling headphones
• Shaped sleep mask (so it doesn’t touch your dried out eyes)
• Custom molded ear plugs (can be up to $200 hearing aid store but are usable in many situations, there are also DYI kits)
• Melatonin (possible unsafe during pregnancy and breast-feeding)
• Sleeping pills (over the counter is fine)

WorkFrom

WorkFrom is a crowd-sourced resource of coffee shops and other such places that are remote-work friendly.

Wi-fi usage

When using unsecured Wi-Fi, consider a personal VPN. We don’t have a corporate VPN but consider purchasing a personal VPN if you travel for Bramble or use unknown networks often.

Remember that if your job has restrictions based upon geolocation (for example supporting customers with specific data restrictions and country-based access), a personal VPN may not be the best choice as often the VPN vendor routes traffic through other countries. If this restriction applies to you, consider tethering. Tethering is when you set up your mobile phone as a hotspot and connect your laptop up to it via Wi-Fi, avoiding the unsecured Wi-Fi network. There is more information here on the subject, and as long as your data plan supports it, you should be good to go. Double check before international travel, as it may be supported but have hidden costs.

When connecting to a network with a captive portal, most websites will not load as modern sites use HTTPS, and captive portals interrupt that process. Your device will try and compensate for this, but it can be tough to manage manually. If you have trouble, try connecting to captive.apple.com first, which is intentionally only HTTP and will load the captive portal.

Troubleshooting

2FA debugging

If 2FA stops working unexpectedly (no new phone or computer) it’s usually because of improperly configured date & time on either device. Make sure that “Automatic Date & Time” is enabled on both devices. If they’re already enabled try toggling them off and on again to force an update. If this doesn’t work, request that ITOps reset your 2FA setting.

Links for finding the settings:

• iOS: Get help with the date and time on your iPhone, iPad, and iPod touch - Apple Support
• macOS: If the date or time is wrong on your Mac - Apple Support
• Linux (using systemd): systemd-timesyncd - ArchWiki

For Android there’s no definitive link, since most vendors have different UIs for their settings. But in the Settings-app, look for “Date & Time” and there should be a “Automatic Date & Time” toggle.