Remote Manager Toolkit

Free Open Source Toolkit with process for managing teams.
Management Remote Teams Open Source organizational models

Remote Manager Toolkit in GitHub UI

Open Source Repo:


Often managing software developers, and other technical staff can be challenging as it concerns keeping notes, communicating expectations, remembering and discussing impact is often hard to do well in a typical not taking application. I’ve seen managers use Google Docs, Word files, spreadsheets and more. A more natural option for a developer is to use the tool they use often, Git. Git and it’s workflows allow for publishing, editing, and collaborating on text.

Put very simply a Software Developer’s job is to edit text files, which include instructions for computers to do work. It has a lot of generally similar challenges to say, an author, politician, or a newspaper reporter, in that we need to write content, edit it, get it reviewed, and eventually publish one of the versions of that work for customer consumption. We may need to even revisit, and edit again, and then publish a newer version while keeping a copy of the older copies as well.

This problem is also present in management, we need to describe process, and manage expectations with a number of people. We do this knowing situations will change, and so we keep running records of what changes are impacting the business, and the decisions that those result in. At worst, this is done mentally from memory, but in larger or more complex operations we choose to often write these things down, edit them, get them reviewed, and eventually publish one of that work for general consumption.

There are many ways to approach this problem, but Software Engineers have come up with an approach and some tooling that’s worked well for them. - In simple we need to track changes, and revisions to files so we can allow one or multiple people to iterate towards the end result they want, knowing they may even need to come back much later and revisit and pick up the process again. In software engineering we call this a Version Control System. There have been many, but one in particular has recently become the primary tool used, and it’s called Git

A Complex Tool Called Git


Source: XKCD

So Git is under the covers is a really complex tool, but we can ignore most of that right now - what is important, is that it is a tool that allows people to securely keep independent copies of files, and each revision made to them. Git also provides us ways to merge those independent copies together so all revisions end up in one place. Git helps us keep track of who made each revision, what the revision specifically included, any notes associated with a revision, and when they did it.

Now - without getting too nerdy here, these are also some key qualities a manager needs when communicating with an employee that reports to them on a number of topics such as goal setting, coaching, onboarding, and role definition. An employee, would probably also benefit from being able to have a copy or dossier of all the manager to employee conversations as well. We can track progress, keep records of conversations, and use these not just to negatively manage under performance, but also help with coaching, growth and ultimately career management.

Git+GitHub for Company Documents

There have been several companies that have started to try to make Git easier to use, from Github, Bitbucket, and others. Many software engineers use GitHub already, live in the tool often, and it enables more distributed asynchronous communication and collaboration on proposing and managing changes to content. - More on this ‘Asynchronous’ idea in a moment.

The most powerful thing Git allows us to do, is propose changes to content in a distributed and safe way.

Company Handbooks

There are some great examples of policies being drafted in Git, and hosted on GitHub.

If we think about this for a moment, these are public company handbooks, but I am aware of company with private Git repositories that store similar content. By doing this, leadership, employees, or anyone with access to the Git repository can propose changes using a Git concept called “Pull Requests” - these work by grouping a series of specific changes, and starting a proposal to get them merged into the original work. By doing this, the changes are clearly visible, and conversation can be openly had about what the changes might mean, and even further changes can be layered on top, until the Pull Request is accepted, and merged.

Here is an Example Pull Request

Example Pull Request Dialog

Notice the dialog between multiple people discussing the changes. This allows us to understand what was proposed, any context at the time that was considered, and the eventual acceptance of the change to policy.

The Exact Changes Proposed from that Pull Request

Example Pull Request Dialog

The red highlighted areas show what was removed, and the green areas show what was added. It clearly helps us see what was changed, so we can focus our review on those changes and what they mean.

You can check out this example on GitHub here:

Career Management with GitHub

Remote Manager Toolkit in GitHub UI

Open Source Repo:

Given all that we’ve discussed, I’ve created a minimum viable open source template for what managing an employee could like like inside a GitHub Repository. The template is public, but in practice these can cloned, and copies can be made private in GitHub, or hosted on private Git servers of your choice. The data is stored in plain text, and styling is done with markdown with no expensive software required. Here are a few critical things to consider why this method may be a good option, or could inspire you to make changes to systems you already use.

A Secure Record of History

One of Git’s main features, is that it needs to make sure that anything put into Git, will be exactly what you get out of it. There is some industry gold standard methods that ensure this happens, and it makes sure tampering with historical revisions is impossible to do without leaving an extremely obvious trail.

This is important - Not all companies have a proven or mature human resources group, and even managers have done the wrong thing and mismanaged employees. Often the people most at risk for HR records being edited, or skewed against them are minority groups, and less privileged. By removing the ability to edit history, it makes the conversation available for audit, and a good manager should be open to audit to protect employees.

Distributed Workforces

Some jobs involve working with people a few feet away, and things are perceived to be easier, but more and more, jobs are spread across offices, timezones, and countries. While managers may be local to their employees, they also may not be, or may not be all the time. One core feature of Git, is the ability to make secure copies of repositories that can be viewed locally, even offline. This means workforces can be more flexible, and more robust. There won’t be a single filing cabinet with HR files that are hard to find, hard to use, or expensive HR systems that are expensive and hard to operate.

Asynchronous Workforces

What does Asynchronous, or Distributed Mean? Read this: The Complete Guide to Asynchronous Communication in Remote Teams

Studies show that as the friction or difficulty of communication increases due to distance, tools, policies, timezones, or other factors increase. This cumulative communication friction as I call it eventually causes a team to start changing how they communicate. This is somewhat obvious, but critical to pay attention too, because every environment is different. Intel once studied that 15 feet was enough distance to make a team work as if they were remote, or on the other side of the planet. While some teams naturally do a great job communicating, studies also show most teams are actually pretty bad at it.

Above I mentioned the key ability for Git to keep track of revisions, a critical element of that, is that Git has ways to safely merge the accepted revisions back together, even if revisions are made by people around world, far away, or at different times of day. There is no need to edit in real-time together. This becomes a huge asset because it means an employee could be in another timezone as their manager, and still have a place to communicate securely and document their careers. While I still am an advocate for face-to-face time with employees, this adds an extra ability that is very hard to find without tool like Git.

Easy To Look Back

Git, especially when hosted on GitHub is very easy to search, look at the history of any given document, and see the overall time line of who said, or did what over time. It’s easy to even go back and add additional thoughts much later about a prior conversation without ruining the prior history.

In practice - Today an employee could email a manager, and ask for coaching advice, and they could discuss this and other things in email. This becomes difficult to manage because trying to look backwards in time is increasingly hard to do in email. With a Git Repository, it’s easy to see the history of any given idea, conversation, or goal.

The company could also invest in a costly and hard to use HR system to manage these conversations, say an Oracle powered system. It’d be expensive, and would only work while the employee was online and had access to the system. Some call that a benefit, but in a modern distributed workforce, that’s a real limiting factor in practice.

A manager could write up a lot of word documents with coaching materials, critical feedback, or similar materials, and store them on their laptop. - Well, that’s ok I suppose, except then those materials still need to be distributed, backed up, and somehow revisions need to be tracked.

Consistently Flexible

This method of working with employees using Git allows for a way to be consistent with the approach across multiple employees, or even across an entire company, while still allowing for documented inconsistency. This is a careful nuance often found in Human Resource conversations.

We need to enforce consistent policies against inconsistent groups of human beings.

This means managers often make exceptions, or accommodations, often times very willingly, but it becomes critical to document those decisions, and why they were made. Git allows us to very easily audit what is different from one repository to another, and what kinds of differences exist. These can be medical accommodations, or vacation allowances, even salary conversations. While these are all sensitive private conversations, HR needs a way to audit and make sure these conversations are reasonable, and acceptable to the business, the employee, laws, and other requirements.

Even if you don’t use Git

Even if the ideas presented above are a bit too radical, or not something you are interested in whole. There are some good ideas I’d suggest considering. Take a look at the topics suggested in this repository, and look at the frequency of conversation. These are all topics that should be discussed proactively with employees. - Remember that we want to manage the future growth and success of the employee, even more so than manage an employee who is under performing. It’s largely the same steps, but assuming a positive outcome, instead of waiting for a problem to arise.

Bringing clarity, and transparency between a manager and an employee is critical as well. No one who works with me should ever be surprised by a new promotion, or by a demotion. Same goes for performance reviews, there will be dialog, discussion, documentation around these points and it helps empower the company and the employee to do the best thing possible.

Drop me a line /about if this has been interesting, or if you have any feedback.