Tandem 2.0

# Improving Tandem

Almost all improvements to Tandem should be contributed to the main Tandem Repository.

PRO TIP

Consult Structure below and if you've got an improvement that doesn't fit then suggest a change! In fact, you can submit a change or idea to pretty much anything here!

This repository seeks to build on the lessons learned from Horoscope. As such, its goal is to continually, incrementally, and iteratively improve the business so we can increasingly focus on the things that matter most while maximizing our flow.

This means that on a high level someone should be able to go there with an idea or suggestion and...

  1. Put it through a standardized vetting, prioritization and refinement process
  2. End up with small, actionable and connected tasks that can be advanced by a team slowly and methodically over some time frame
  3. Make contributions into a predefined and obvious structure
  4. Have their contributions automatically deployed to the places where they have the most impact
  5. Improve Tandem by removing repetition, variables and confusion from our work

# Understanding the specifics

Specifically the repo...

# 1. Is a single source of truth

This repository should hold anything that makes Tandem run better, faster and stronger but it should do so within a well defined structure so its obvious where things should go. In this way it should act as an intuitively organizied single source of truth for our most important assets.

A caveat to this is we don't want to include anything that should obviously be its own repository. For example things like specific project repositories, start states, seeds, modules, plugins, etc should exist on their own but should also be tied to this repository in some way.

Beyond the above caveat its important for this repo to contain as much stuff as possible. This reduces cognitive load, increases transparency when important things change and helps maintain company-building momentum.

# 2. Ties things together

Its not enough to have a single source of truth floating in isolation in the aether; it needs to have practical value and be useful. To that end, this repo, like a good rug to a room, needs to also tie everything we do together. This means that when we add or update this repo with something, that something needs to also surface, ideally via some sort of automation, someplace else where it makes sense and can be put to use.

Here are a few specific examples of how we can tie things together:

  • Employee handbook or company documentation changes automatically notify people on Slack
  • Project README template improvements automatically open pull requests on downstream repos
  • Aforementioned README templates link back to helpful documentation stored here
  • Project start states can pull in new scripts and Lando plugins from here

It's difficult for a human to consistently remember to come back here for the things they need. Let's use the robots to make sure we are shipping things from here to the most useful places.

  • @TODO: Would be great to actually have the above things so we can SHOW instead of TELL
  • @TODO: the exact engineering mechanisms around parts of the above of this need to be better defined and will likely be one of the first things we tackle

# 3. Provides a resilient process

The final piece of the puzzle here is to define a resilient process we all can use to surface important issues or questions and then work, ideally together, on improving how we do things. The process should be

  • Easy to understand and document
  • Require minimal oversight
  • Mostly asynchronous
  • Run on its own inertia.

It should also provide some "objective" prioritization mechanism and encourage tasks be broken into very small chunks that are worked on in teams of two or more.

  • @TODO: This needs to be defined and fleshed out a bit more.

# Understanding the structure

So while anything and everything that makes Tandem run better, faster stronger is our high level metric around inclusion we do currently have a more concrete and extant structure.

./
|-- .github                           GitHub templates and config
|-- .platform                         Platform.sh config
|-- docs                              Docs and templates
  |-- .vuepress                       Vuepress config
    |-- components                    Vue components
    |-- public                        Static assets
    |-- config.js                     Vuepress config file
    |-- enhanceApp.js                 App level customization
    |-- override.styl                 Stylus constant overrides
    |-- style.styl                    Extra styles
  |-- guides                          Tandem guides and how-tos
  |-- handbook                        Tandem employee handbook
  |-- manifesto                       Tandem manifesto and values
  |-- templates                       Tandem templates
  |-- README.md                       Documentation homepage
|-- site                              Follows similar structure to /docs
|-- scripts                           Helpful Tandem scripts
|-- .lando.yml                        The Landofile to power this locally and in CI
|-- .travis.yml                       Travis CI for build, test and deploy
|-- package.json                      Node dependencies and config

First and foremost this repo contains our manifesto, employee handbook and actionable guides to accomplish specfic things eg our documentation. It also contains our website and other useful toolz.

# Manifesto

docs/manifesto

The manifesto should be our most immutable documentation. That is to say that it should not be modified without significant deliberation and consideration.

It should contain:

  1. Why we exist and our mission
  2. Our core values
  3. A roadmap for growth
  4. An overview of how we got here (our history)
  5. Roles and responsibilities for Tandem
  6. How the above things connect together eg an org chart

# Handbook

docs/handbook

The handbook should be the place for all new employees to get spun up and integrated into the Tandem way with minimal disruption and loss of flow. It may also store other helpful information about the comapny that does not belong as either a Guide or in the Manifesto. For example an enumeration of our sales channels or how our sales process works might fit best in the handbook.

It should contain:

  1. The things an employee needs to do on their first day to get rolling
  2. Company policies around benefits, pto, etc
  3. Other relevant materials that do not fit as Guides or within the manifesto

# Guides

docs/guides

Guides should ultimately seek to answer questions like How do I do X at Tandem?. They should be written for people trying to do something for the first time. This maximizes team flow by reducing the time spent showing someone how to do something, allows knowledge to be transferred in a standardized way and builds a more resilient and redundant team that more or less does things the same way.

That said, guides should always be just a starting point in the move towards higher levels of automation. We should constantly and continuously be trying to reduce the size, complexity and time spent going through each guide in favor of the robots. To that end we are advantaged if all our guides follow this "Guide Journey":

  1. A rough sketch or outline of a process is created
  2. The sketch is fleshed out with helpful details, scripts, templates, etc
  3. The robots are used so that manual steps like running a script, copying a template or populating a backlog are done automatically

PRO TIP

Guides are best written with a singular and specific focus and contained within a singular markdown file. This helps to minimize overlap and confusion while maximizing portability and ease of writing, amongst other things.

Some examples of guides are things like:

  1. How do I spin up a project?
  2. How do I Tandemize an existing project?
  3. How do I send out invoices?
  4. How do I qualify a sale?

# Templates

docs/templates

If Guides serve as a high level view of how something should happen then Templates serve as, at least part of, the what. This means that templates should be deployable scaffolding for use in various projects and products. Ideally they can be pulled directly from here and surfaced in downstream repos so we can make changes in one place and then update things downstream.

While there is no strict rule around what kinds of templates can live here, here are a few examples:

  1. Project READMEs and related docs eg architectural plans, project briefs, etc.
  2. Project tickets or issues that should exist in all our work
  3. GitHub issue and pull request templates
  4. Metadata for common tags to use across projects
  5. DevOps templates like .travis.yml, .lando.yml etc

In the aim of efficiency many templates should try to connect back to other guides contained within this repo so we can do our best to tie things together.

# Automation scripts

scripts

Scripts or Lando automation that can be used on many projects can live here as well.

  • TODO: We still need a good delivery mechanism for this but it would be great to centralize and distribute useful things like
  1. platform.sh DevOps setup
  2. Project scaffolding scripts eg automatic population of issues, labels, READMEs, etc
  3. Lando commands to pull databases/files from platform.sh

# Suggesting a change

Suggesting a change is very straightforward. Create a new issue and write it up as you weill. Initially we created specific and well defined types of issues you could select from but that ended up being fairly tedious, restrictive and perhaps counter-intuitively more confusing. Our current modus operandi is to keep things open and define an issue how you like. It can be a large initiative or a simple and straightforward task, a stub with just a title or a lengthy essay. It can be whatever you want it to be! The main goal is to stay organized and get a birds eye view of what things we are doing to improve the organization.

# Managing the process

The formal management around our improvement process should be relatively low-touch and mostly run on its own inertia. It will primarily feature an all hands on deck meeting run by the Keeper(s) of the Faith (@todo: link to this role and who occupies the role) at the end of every week eastern time and it will last for one hour.

All other collaboration and communication should be async with a sprinkling of ad-hoc meetings as deemed necessary. The Keeper(s) of the faith will be primarily responsible for managing the Kanban board and function as "project managers" (@todo also link to this role when its up) of the "Tandem product".

The content and agenda of our the formal Friday meeting will change based on where we are in a given cycle but should generally follow this pattern:

# 1. Determining focus

We likely will have casually discussed the next focus or milestone of our company building activities beforehand but the first meeting of a new cycle should determine a focus (or two) to advance.

The result of that meeting should be...

  • A GitHub milestone (and/or release?) with a start, due date and details about the agreed upon focus
  • A populated backlog with a reasonable amount of story points for the milestone
  • A few initial issues assigned to everyone

# 2. Working, collaborating and showing

Once a focus has been determined and tasks assigned, subsequent meetings should by run in general standup format until the milestone is completed. This should minimally include normal standup things like progress updates from everyone on in progress issues, unblocking blockers, etc but on occasion it may be appropriate to optionally mix in some combination of these things as well:

  • Milestone management - Are we on pace to achieve the milestone? Do we need to pivot or alter the plan? Is there another pressing milestone or focus that we need to work on concurrently?

  • Show and tell - Are their any big ticket things that have been changed that need to be shared in a lunch-and-learn style format?

  • Discussion - Are their any discussion issues that have gotten WAY out of control and could benefit from a group chat?

  • TODO: should we have formal meeting agendas and/or note taking to help this process since they could differ a lot from meeting to meeting?

# 3. Retro and Repopulating

Once the milestone is completed we should perform a retrospective on this process and whether we can improve it. If we can then we should spin up a brief cycle with process improvement as the milestone.

  • @TODO: agenda for this?

# Choosing and working on tasks

Generally and ideally you should be working with at least one other person on any task(s) assigned to you that are also associated with an active and in-progress milestone. There are a few things to expect there

# 1. Responsibility

If you are the only person assigned to an issue then you are singularly responsible for completing that task. If you are assigned to a task with more than one person it is up to all the people on the task to figure out how the work gets divvied up but regardless of how that happens you are all equally responsible for getting the task done.

# 2. Staying active

There will be circumstances where you are not assigned to any tasks but you have time to work on stuff. In these situations you should self-assign a ticket within an in-progress milestone. Ideally, you will also find at least one other person to work on the issue with you. Obviously ask them if they want to work on it with you 😉

In some circumstances there will be no tickets in the current milestone(s) that you can advance either because the milestone is almost done or because you are not sure how to advance the task. In these situations you should select any ticket that you feel capable of advancing. Obviously use your best judgment to select a ticket that will bring value to Tandem as soon as possible. Tasks labeled as one-off may be great first candidates.

Quarterly Review →