Axelerant Engineering Handbook #

Note: This handbook is close to release but not quite complete. Please edit the pages using the link at the bottom.

What is this? #

This handbook documents The Axelerant Way for engineers at Axelerant. It is neither a guide nor a tutorial for a specific language or technology we use at Axelerant. Rather, it aims to show an engineer at Axelerant what we value, who we are, and how we work. It helps you understand what you need to do to succeed at Axelerant.

Taking inspiration from ideas such as the above that focus on “why”, this handbook also focuses on why we make decisions the way we do. We cover how we work, of course, but we also primarily try to convey why we do that so that you can decide the circumstances in which you may choose not to follow the guidelines here.

Who is it for? #

The primary target audience for this handbook is an engineer who is new to The Axelerant Way or someone who needs a reminder (we all do, from time to time). When we say engineers in this handbook, we are referring to those who are involved in defining, writing, reviewing, testing, deploying, and operating any software system. At Axelerant, this includes developers with backend, frontend, QA, and SRE competencies (as of this writing).

We will avoid diving too deep into specific technologies and instead link to resources and references that will do the job. Reading those references is an important part of reading this handbook.

How is the handbook structured? #

The handbook begins with the principles that we follow when working at Axelerant. We further elaborate on some of those principles in the next section which is to do with behaviors we expect from each other. This is followed by a section on being productive. While the target audience for these sections is engineers (like the rest of the handbook), these three sections are probably suitable for all Axelerant team members.

We then cover general guidelines on technical topics. We talk about generic technologies first: concepts that will likely be required regardless of what you work on. This is followed by re$$ferences on specific topics such as Drupal. We try not to replicate what’s already out there. Instead, we link to those resources and give pointers on our standard practices. We also understand that software development largely depends on the requirements. That is why, all of this is prescriptive, not mandatory.

Relationship to Onboarding #

This handbook also serves as a constant reference during engineering onboarding. Our intention is to build the handbook along the framework of PPP: principles, practices, and platform. The first two sections of the handbook already match the first two components of that framework. The “platform” component is woven throughout the handbook and will also be maintained elsewhere as “Axelerant Minimum Viable Platform”. This is currently work-in-progress.

Contributing to the handbook #

You can suggest any changes to any of the pages by clicking on the “Edit this page” link at the bottom of each page. You can also use Github to add new pages to the handbook. As an engineer, you might want to clone the repo in your environment (or use Gitpod) to make changes.

We welcome all contributions to the handbook, including from people outside Axelerant. That said, this handbook is meant to be opinionated and a (relatively) long-term guide. This is why we may not be able to accept all the changes we receive. Please read the above section to discern the intention of this handbook and hopefully, that can explain why we may not be able to accept your contribution.

In all cases, we follow the principles we have written here in responding to the contributions as well. Specifically, in case we can’t straight-away accept your contribution, we aim to be kind by working with you to change your contribution so that it can be accepted. We do that by sharing feedback about why we can’t accept your contribution as-is.