Let’s imagine this scenario: Today is the first day of your new gig. With overwhelming nervous energy, you’re awake so early you wonder how people normally wake up at this hour, you even combed your hair today (maybe even showered?) and you’re ready to put your best foot forward and conquer the world. You have some calls introducing you to the company, and then you’re left alone and it’s time to set up your computer.

  • Does the company have preferred linting tools?
  • What formatting standard do they use?
  • Does the company log into AWS using federated access or access keys?
  • Are you getting an error because they don’t give new hires full permission, or did you mess something up?
  • Should I be trying to build this code locally?
  • Do they build directly on the machine or in a Docker image?
  • What version of Python should I be using?
  • What else do I need to be productive?

At Mphasis Stelligent we recently open sourced our DevOps training platform: Stelligent U. This is the same process that we use internally at Stelligent to ensure that our engineers are ready to work with clients and be an ambassador for the Stelligent. We have put a lot of thought and effort into our new-hire experience and care about the onboarding process. 

We have a section dedicated specifically to getting a development environment setup. It can be used in full or customized by your organization based on its policies. The module goes into detail on setting up AWS access keys for programmatic access. It also covers GitHub repositories and using AWS Cloud9 for a development environment.

Now, back to our scenario: You keep asking questions but after the seemingly fiftieth question, you start worrying that you’re taking up too much time. Is there someone else you could be bothering? Since you don’t have any contacts, your choices are:

  • Keep asking the same engineer
  • Try to solve issues on your own and start making assumptions
  • Space out your questions so at least you’re not rapid firing questions even if you’re wasting time between questions
  • Wait until another engineer gets in your crosshairs

After this internal debate, you may have a sour taste in your mouth about the new organization. You may also dream of your previous job where your entire development environment was set up perfectly. At your previous job you were at peak efficiency and knew how to get around like the back of your hand.

Types of Organizations

There seems to be three archetypes of organizations in regards to onboarding new employees and getting their local environments set up:

  1. Organizations that don’t have any documentation. The entire setup is completely tribal knowledge. You have to rely completely on someone else’s instructions that they come up with ad-hoc. You bug someone repeatedly until they run into an issue or they get tired of helping you and suddenly you’re someone else’s problem.
  2. Organizations that have everything perfectly documented. If something doesn’t work, it’s because you messed something up. It’s impossible for the documentation to be wrong or out-of-date. If you think something is incorrect, you will have to prove it to a hierarchy of co-workers and it will become an ordeal.
  3. Organizations that try to document the setup process. Things may be out-of-date or even incorrect with the documentation, and it’s not a surprise. Within this archetype, there are two subtypes:
    1. Where the documentation isn’t updated on a regular basis. You follow the documentation and frequently get stuck and have to ask questions. You encounter problems that require multiple engineers to troubleshoot. When the issue is resolved, you have no idea what caused the resolution. In order to document the resolution you have to either: document everything that you went through; undo everything and try to solve it again; or document the last thing you did. Generally, the resolution doesn’t get documented. The next new hire will be coming to you when they have the same issue and the process repeats.
    2. Or organizations that actively encourage new employees contributing to the documentation as they go through it. The process for contributing is documented and there is a review process in place. The documentation is iterative and improved for everyone. If a new employee is an expert in one area, they can introduce better explanations and processes for everyone. If they’re weak in another area, they can rely on the work of previous employees.

The documentation in our Stelligent U platform goes over the process of setting up a development environment. We make it a reliable and iterative process that evolves as we do and minimizes the amount of hand holding that is necessary to get a new engineer up and going. We document the process thoroughly but accept that it’s not perfect and encourage engineers to contribute as they are able.

Standard Development Environment

It’s important for organizations to have a standard development environment. It allows new hires to get up and going as quickly as possible. They don’t have to reach out to multiple sources, search for tribal knowledge or be stressed by debugging when they’re already stressed from starting a new position. The more documentation available to new hires the less hand-holding by another engineer they require. It also ensures that no step is left out which can lead to realizing you didn’t install some vital software that every other engineer is using down the road. It helps to speed up the setup process and make it as efficient as possible. We make it a goal at Stelligent to have every new hire contribute to the documentation as they go through it. This helps the documentation stay up-to-date, clarify confusing steps, add missing requirements and the employee can make an important contribution on their first day.

Contents of Development Environment

What should be included in a standard development environment?

  • Access to source code. You need to be able to access the code in order to change it. Even if you’re writing an application completely from scratch, you want your code stored with the rest of the company’s code rather than in a silo. You don’t want your repository to be a snowflake. You need the ability to both read and write to the company’s code so that you can push up your changes once you make them.
  • Being able to debug changes you make. Once you make a change to the source code, you need to be able to test that it has the intended effect. Hopefully, you can have an approximation of the production environment running on your local machine. It allows you to iterate faster and not interrupt work being done in a shared environment. If you’re not able to have a local environment, hopefully you’re at least not making changes in production!
  • Access to documentation. The documentation should also be organized and easy to read. You should also have the ability to contribute and modify the documentation easily.
  • Having an editor with appropriate tools available. Although possible to do all of your code writing in Notepad, it’s not recommended! Having an appropriate code editor allows you to have utilities like linting, error checking, and code auto-completion. You can write code faster and use a consistent style across the organization. A consistent style allows code to be read and understood faster by everyone. The learning curve with the editor should also be considered. Although I personally prefer and use vim, if you require or even suggest that all your new hires use it, you may face a mutiny from the uninitiated.

Deviations from the Standard

Developers should have the ability to go outside the standard development environment. This deviation allows them to use tools that they are familiar and comfortable with. They may even find better tools as they become available.

This customization should be done at the engineers’ own peril however. If an issue comes up with their customized environment, their first troubleshooting step should be falling back to the standard environment. Otherwise, you have co-workers attempting to troubleshoot tools that they have never used before. This frequently requires the co-workers to essentially learn the tool themselves.

Your standard development environment should be dynamic. If all, or even the majority, of your engineers are making the same deviation then consider updating your default environment. The standard environment should be a building block and not a strict requirement.

Stelligent U

While the module in Stelligent U can be used as a starting point for your company’s development environment, it should change with your company. Not only do technologies evolve but new processes emerge. Your development environment should be a snapshot of your company’s policies at a certain time and not remain static.

We’ll be updating the module as our internal processes change, but the development environment won’t be a reflection of your company. If you come up with a better way of doing things, please submit a pull request so we can review the change and potentially make it available downstream. If your company is not using AWS, we want to hear from you! We would love to be able to offer development environments for different technologies.

A standard development environment helps reduce stress and provide an optimal onboarding process for not only your new engineers, but also your existing engineers. Without a standard development environment, they may be spending significant time and resources getting your new engineers up and going.

Stelligent Amazon Pollycast
Voiced by Amazon Polly