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:

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:

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:

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


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:

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:

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: