Welcome to Vokal!

There are a ton of links in this document, and each one has more information you can use to read up on how we do things. Take as much time as you need to read through everything, and always feel free to ask your coworkers about anything you don’t understand.

Remember: It’s always better to ask if there’s something you’re not sure about, whether it’s policies and procedures or how to do something in code.

Talk to the director of your department if there’s anything missing, unclear, or incorrect in this document.

How to approach this

There's a lot of information in this document and the repo that contains it. It's probably a good idea to just skim over everything first and get a sense of what's available before really digging into anything. Here's what we'd recommend:

• Start by reading through this document
• Skim through the rest of the top-level documents in this repo
• Skim the documents in the subdirectory for your discipline
• Deep breath
• Take a closer look at the links from this document
• Read through the coding standards for your discipline
• Collect notes and questions as you go. We're always tweaking these docs, so let's improve anything that isn't clear.

Ready? Of course you are.

What am I doing here?

As an engineer at Vokal you have two responsibilities:

1. Write great code
2. Bill clients

We expect you to do more, but your core function is to satisfy these obligations. You are doing a good job as long as you are writing great code and meeting your utilization requirement. If you don’t enter your time in our time tracking system, we cannot bill clients for your time and you are therefore not doing your job.

Who are these people?!

One of the hardest things to do when you’re first starting a new job is get names and faces straight. We’ve found that something useful for being able to pick your coworkers out of a lineup is the team page from our website.

Britani will ask you to fill out a bio form so you appear on the team page, and coordinate a photo. If you want to make changes to your page later on, she can help you with that, too.

Project Structure

We use the Agile development process. If you’ve never read the manifesto itself or its Twelve Principles, it’s good to take a second to take a look at them. The principles behind them drive a ton of modern software development, including our entire process.

We use the Scrum flavor of Agile development, and if you’re unfamiliar with it, Wikipedia’s got a pretty solid explanation of the roles and standard meetings in this process. We’ve also got a copy of the Scrum Alliance’s Scrum Overview doc for your perusal.

The biggest thing to keep in mind with our adaptation of Agile is that while we do have pretty well-defined processes and tools, if you find that one of our tools is slowing you down or keeping you from doing your work, bring it up—particularly if you have a better idea. The purpose of Agile is to empower teams to find their own way to continuously improve their processes and tools.

You can find additional information about the scrum process on the Vokal wiki. If you still have any questions about Scrum or Agile, don't be afraid to ask your director.

The tools we use for projects

On a day to day basis, we use these web-based products to get our jobs done:

• Gmail and Google Hangouts for communication
• Git and GitHub for source control (If you can read this, you’ve already got that set up.)
• Jira for creating and managing user stories, as well as both internal and client-facing bug management
• SpringAhead for time entry
• Slack for chat. You can create an account there using your Vokal email address. It was setup before we switched to @vokal.io, so just use @vokalinteractive.com as the domain on your email address when you sign up. You can then chat through the web interface, or by downloading their desktop or mobile app. Check the list of channels and join the ones you're interested in. For project channels, you'll need to be invited, so ask the product owner on your projects if the team is using Slack.

Please create a GitHub username if you do not already have one, and give it to a Director or Senior engineer in your department so that you can be added to the Vokal team. More on GitHub in a minute.

For the other services, a combination of Britani and your director will get you set up with accounts. If you have not already received invites for these services, go make sure to bring it up with them.

Note: We strongly recommend using a tool like 1Password or LastPass to keep track of your logins, as you will likely wind up having to manage a bunch of them as you work on an increasing number of projects. They also facilitate using complex, non-repeated passwords that you don’t actually have to remember, which helps protect against hacking, password breach, or the occasional massive security hole in a major SSL library. Two factor authentication is also strongly encouraged for your Vokal accounts.

Two-Factor Authentication (2FA)

All Vokal employees are required to use two-factor authentication on any internal accounts that support it:

• Google: At https://myaccount.google.com/security, scroll down to 2-Step Verification
• GitHub: https://github.com/settings/security
• Slack: https://vokal.slack.com/account/settings
• Dropbox (if you have access)
• AWS (if you have access)

We also suggest turning on two-factor for any other accounts that you use for work as well (Evernote, etc). The recommendation is to use Google Authenticator but you can use whatever tool you like.

How We Build Stuff

Estimation

When we create a development backlog, or list of things that need to get built, we try to break those things down into small enough components to make reasonable estimates of how long it’s going to take. When estimating, points are equal to hours; i.e. a 13 point story in Jira should ideally take 13 hours to complete.

Make sure that when you’re coming up with your estimate of effort, you include the effort it will take you to build the feature to completion, including testing and design integration. Consult with your PO about whether you should add time for integrating client feedback, or whether they will add that as an overage to your estimate; different POs and projects presently handle this differently. If you think a feature is too complex to estimate, break the component down into smaller pieces.

Read these tips on creating good estimates. If you have any questions about how you should be estimating your tasks, please don’t hesitate to ask a Product Owner for help—that’s why they are here.

Git Repo Management & Code Reviews

If you’ve used GitHub for open-source development, this will be familiar. If you’re coming from a position of only ever working on branches with a single repository, this is going to be a whole new world.

We use the fork-and-pull model of Git development. We start by creating a single main repository under the Vokal account (Note: If a Vokal repo does not exist for your project, please speak to a Senior or Director in your discipline, who can create one for you).

Each developer on the project creates their own fork of that repository, committing only to their repository as they build features.

When a feature is completed, the developer pulls upstream changes (i.e., any changes from the main Vokal repo since the last time they pulled from it) into their branch, corrects any merge conflicts, and opens a pull request to the main Vokal repo. The pull request can only be merged after the code is reviewed by at least one other engineer. Here at Vokal we say "Good to pull" or "LGTM". Animated GIFs and emojis are excellent ways to add color and depth to your code reviews.

Why do it this way? The biggest advantage is that it allows developers to constantly be pushing their code to the remote repo, but keeps code reviews clean by tying them to a single pull request.

Keeping things in separate repos also prevents any accidental merges—there is no "NOOOOO! I didn’t mean to merge that to master!" with this system. All merges into the main code base must be purposeful and reviewed by another engineer.

Test ALL the things!

We always strive for thorough test coverage of all of our code. Consult a Senior Engineer about how our automated testing works in each discipline; tests are run on an automated basis after merges into the main Vokal repo to ensure that added code doesn’t have unintended side effects.

Tests will generally be of two types: Unit tests, which test a single component in isolation, and integration tests, which test how two things interact with each other. A good, quick introduction to what each type involves is available in this blog post, but the tl;dr is that unit tests alone can’t catch everything—you have to test how the different pieces of the puzzle work together.

Again: make sure that when you are creating estimates for building components that you include sufficient time not just to write the code required for a component, but to write any tests required to make sure it works the way it’s supposed to.

Moving Stories through Jira As You Work

In Jira, each story has several statuses as it moves through our workflow. Here are basic guidelines for when each status is/should be used:

• TODO: This is the default state when a story is created and added to the backlog for the current sprint.
• In Progress: You should mark something in progress as soon as you begin working on something locally.
• Done: You should mark something as delivered when your code has passed review and been merged into the main repo, and the Product Owner is able to verify it (in some cases, this may also mean waiting until code is pushed to staging).
• Rejected: Your Product Owner will mark something as rejected after it has been delivered if it does not meet the requirements of the story. For example, if there is a story to add a log out button which logs the user out, and the application crashes when you attempt to log out, the PO will reject the story.
• Accepted: Your Product Owner will mark something as accepted if they have given the thumbs up to your work on this story (ie, it has met the Definition Of Done™ for your project).

Note for stories which require multiple pull requests, you should not move the story into the Done status until the final pull request is approved and merged. This is because your product owner will not be able to do any testing of this story until all the code is in.

Assorted Useful links!

You may want to bookmark some of these:

• The Vokal Wiki. Although it's not really a wiki, this is where documentation from outside of the engineering department lives. You might be especially interested in these items:
  • Our Employee Handbook can be found behind the login on Paycor. Tell Allie if you notice anything missing, confusing, or incomplete.
  • The Time Off Request form. While we have unlimited PTO, we do need to know when you know you’re going to be out so we can plan around it.
  • The Team PTO calendar is helpful for planning PTO and for knowing why the hell Owen isn’t around today. You can use the "+ Google Calendar" button at the bottom right to add this to your account, so you can see scheduled PTO alongside your calendar events.
• The Vokal Engineering repo (which is where this document lives) has detailed standards for every discipline and a great deal of general documentation for all of the engineering teams.
  • The Career Steps documents have great summaries of the responsibilities and goals of each step.
• The Vokal Code Labs provide some exercises you can do to get up to speed on our tools and processes. Use your Vokal Google account to login. Start with the ones listed under All Departments, then move on to those specific to your department. Note that not all departments have labs yet; if there aren't any for your department, or if you have ideas for others that would be helpful, talk to your department head (or, if you're feeling really ambitious, open a pull request).
• SpringAhead is kind of clunky, but you still need to log your time there.
• The Vokal Twitter Account is here, if you have not yet rage-quit Twitter. The Social Media team runs it, so if you see stuff you think we should be tweeting about, send it to socialmedia@vokalinteractive.com.
• Do you enjoy playing video games? Many Vokalites play during the lunch hour to take a break from work. Common games include: Overwatch, Hearthstone, Mario Kart 8 and Rocket League. Send a message in #games to see what others have planned and join in the fun!

Frequently Asked Questions

Q: Who do I bug about paperwork for setting up direct deposit, insurance, and other sundry administrative nonsense?

A: Britani, our benefits leader.

Q: What if I need to access the office on the weekend?

A: The front door to the office will be locked, so make sure you see Britani ahead of time to get a key. Note, the HVAC system is turned off over the weekend so you may freeze and/or roast.

Q: Why is Vokal sometimes typed VOKAL or VOKAL Interactive?

A: Our branding changed from VOKAL Interactive to just Vokal, so use Vokal going forward and fix old references if it makes sense, mainly with externally facing references.

Q: Are you guys serious about the 40 hour workweek thing?

A: Yes. We’ve found that people are less productive and make more mistakes when they’re exhausted, leading to more rework. If you’re regularly putting in more than 40 hours a week, something’s gone haywire. Please make sure you talk to someone about it.

Q: May I improve a project or process?

A: YES! YES! YES! If anything at Vokal could be improved you are more than welcome to get to work on it. We hired you because you’re a self-starter genius. Don’t rest on your laurels and don’t wait for anyone else to fix anything.

First-day checklist

The director will help make sure you're setup with everything you need, which will include some or all of the following:

• GitHub access (you should have this already, since you're here)
• HockeyApp/App Center access
• Artifactory access (Android)
• Apple Developer access (iOS)
• App Store Connect access (iOS)
• Device ID added to Apple Developer (anyone with an iPhone/iPad)
• AWS (Systems, Web)
• Drone (Systems, Web, Android)
• Added to team meetings and/or 1-on-1 meetings with your supervisor