Using Github to track issues with physical space

Tracking problems in an office can be an onerous and frustrating task. Some companies designate one person to be the central point of contact for everything from changing lightbulbs to asking the landlord to repair a roof leak.

One thing I helped start at a past employer was an issue tracker for problems around our office. We used Github Enterprise (GHE) and Zenhub, so, naturally, we created a GHE repo to track issues around the office. This process helped us manage problems and manage better what we raised to our facilities manager, who was our conduit to our landlord.

The core of this idea was a carefully crafted set of labels describing who we felt was responsible for fixing a problem, what kind of problem was it, what aspect of our productivity was affected by it, and where the problem was located in the office.

Responsibility

We decided that responsibility to address problems fell to one of three entities: our facilities manager, our landlord, or a vendor we’d hired to manage some of the appliances around the office.

Issues such as “change lightbulbs” or “get a new projector” obviously fell to our facilities manager. When someone had a particular preference for how something should be addressed, GHE was a great way to record it. For example, if someone wanted the replacement projector to have a certain feature, they could simply leave a comment and hope that it would be read and honored.

Issues such as “fix a roof leak” or “the rear elevator isn’t working” fell to our landlord. Our facilities manager would communicate the issue to the landlord but the issue made it clear that ire for “it’s still not fixed” should be directed at the landlord, not at the facilities manager.

Issues such as “the pop machine’s bill reader does not work” or “the coffee machine is bricked” fell to the concessions vendor.

We prefixed this label with “Action”, so our labels were “Action: Company”, “Action: Landlord”, and “Action: Vendor”.

The most important part of this label was establishing a flowchart for people to determine responsibility. You can download the source for this flowchart.

Building Problem Assignee Determination Workflow, source available

Nature of the problem

We largely used tags prefixed with “Nature” to give a hint to the facilities manager or landlord about what kind of contractor would be necessary to fix the issue. For example, a plumber might charge a visitation fee, so it was efficient to build a list of things for a plumber to do. Likewise, an audio-visual contractor would prefer to send someone out once with three projector bulbs and a new HDMI cable to run instead of four times.

Our natures were AudioVisual, Doors, Lighting, Plumbing. Each of these are pretty obvious, except Doors: that generally fell to a general contractor. Doors are a security feature!

Productivity Affected

It’s important to understand how problems affect the emotions and productivity of those that encounter them. We use a variety of labels to represent how our daily lives are impacted by these problems. Some of these labels are closely related but differentiate some nuances.

Usability problems encompassed counter-intuitive interfaces or things that needed to be explained through signage. Is someone always racking the dishes in the dishwasher incorrectly or overflowing the sink because they put loose-leaf tea down a skinny drain? A sign or some education could help. Sometimes, these issues would result in a better coffee machine or a new always-there computer that didn’t require tribal knowledge to operate.

Presentations problems are generally of an audio-visual nature and inhibit collaboration in conference rooms or other meeting spaces. If a projector was broken or a microphone battery was failing, it was a presentations issue.

Cleanliness problems represent issues of regular, periodic cleaning or a mess than someone had made and not redded up. These could be messes in the copy room or a spilled bag of tea that no one took the time to scoop into the garbage can.

Health problems are more serious in nature, generally representing biohazards of some kind. A lack of soap in bathroom dispensers or “science projects” in the refrigerator bear this label.

Safety problems are the kind of thing that OSHA would care about. Is a stairwell insufficiently lit? Is an elevator’s inspection certificate out of date? Is a pipe’s suspension wire rusted and ready to fail? It’s probably a safety issue if the problem makes you want to entirely avoid an area.

Pride problems include pretty much everything else. If a problem came to mind and brought with it feelings of embarrassment or a sense that no one cares, then it is problem a pride problem. These are the “broken windows” that are all too often neglected until there are a lot of them.

Rooms

The utility of this last one is pretty obvious: we wanted an easy way to show rooms that have a lot of work to be done. In a worst case scenario, it could show rooms that are unusable because of a combination of problems. GHE’s label filters work great for this. We prefixed each room of the office with “Room”. Issues affecting the open office floor space did not have a label associated with them, although we could have done that more semantically by using “Area” instead of “Room”.

Other labels

We had to have some others in order to organize better. Duplicate, Invalid, and Wontfix rounded out our label set.

What it looks like

I’ve setup something like this for Code & Supply’s Workspace, a co-working space I use in Pittsburgh. I filed a few issues right away to show the utility of this system.

Notice how each issue has a set of labels. Notice also that this isn’t using Github 🤓

Notice that not every issue has one of every label. The one that is mostly commonly omitted is Nature. However, I’m sure that savvy folk could establish some additional natures to use.

Finding things

The last part of this was key: making it easy to list issues. We came up with a list of common searches and listed them, with links, in the README.md for the repository.

  • Issues for facilities manager to solve
  • Issues for our landlord to solve
  • Issues for our vending company to solve
  • AV electronics, Lighting, Door, and Plumbing problems each

This made it very easy for our facilities manager to find the issues we cared about and raise them to the right people.

Curation and execution

We formed a team that met for 30 minutes weekly to go through the backlog. One person who was a manager and a little higher up on the totem pole than some of the other managers took charge and represented our interests to the facilities manager, our employer, our vendors, and our landlord.

Experience

This worked out well for that team. It’s still in use and helping people to get things done! It’s a system I have brought to C&S and will bring to my future employers.

Thank you to several good folks of the Code & Supply Slack chat for proofreading!