Where is everything? - Keeping track of project details

Quickly find where everything lives for a project with a little proactive documenting

You can reduce stress and proactively answer questions by creating a document highlighting the locations of everything in a project.

In this article I will show you the document structure we’ve recently adopted to help get, and keep, a handle on several projects. What do you mean? Of course I’m not writing this as a way to remind myself of some of the projects I need to get back into in the new year!

Why document where everything is?

In larger companies there will (hopefully) be something in place for each project. In smaller companies, like ours and many we work with, there isn’t a person, team, or external reason to have good hygiene around documentation like this.

If you always use the same stack for everything, you might not have need for this, but here are some reasons why it is useful.

  • As a starting point when considering cost saving
  • To jump back into a project I’ve been away from for a while
  • As a starting point when considering data protection issues
  • To improve onboarding a new person into the project
  • To think about what someone leaving a project might need removed from

How to document where everything is?

I’ve seen documenting like this ranging from completely informal (ask so-and-so on Slack), to over the top documents explaining the location of other documents, explaining what you need to know.

We’ve found a simple spreadsheet works well. It is:

  • Easy to share
  • Quick to keep up to date
  • Can act as the single source of truth
  • Spreadsheets are easy to customise for specific projects
Spreadsheet with a heading called Example Project and example/dummy data entered for production and staging URLs and some of the project locations, like Code Repository and Web server. They link to dummy URLs and have comments like 'should move to clients org'
Example of the spreadsheet we use, if the image appears squashed, open it in a new tab

You can view a sample spreadsheet but given how quick it is to set up, I would suggest creating one from scratch tailored to your needs.

In ours we list;

  • Production and Staging URLs
  • Code locations
  • Hosting locations
  • Errors/Reporting locations
  • Wider networky things, like DNS, Domain Names, Email hosting

For each of the locations we mention;

  • The company involved
  • The URL to the item
  • Who owns it (we care about us/client/someone else)
  • Do we have details stored somewhere
  • How much it costs
  • Comments

It is important to know what we as a team/company have access to, so we can remove our access when no-longer needed. It is also useful to direct a client to the best place should they think it is something we could do.

We only record how much something costs if we’re paying, we use this as a starting point for conversations around value and cost-saving.

We prefer our clients own everything, these spreadsheets let us see what things we should try and move to them.

Keeping things up to date

The best times to update the spreadsheet are;

  • At the start of the project, by cloning a new spreadsheet you can start to consider some of the things you may need
  • At the point someone adds, updates, or removes something
  • At regular intervals, once a quarter is a good cadance for reviewing live projects and making sure all information is up to date

It surprised me how little some clients know about who owns what, so share any spreadsheets you create with them for their knowledge.

Recent posts View all


The best way to test model scopes in Rails

Learn about Rails scopes and how to best test them with both Rspec and Minitest


Finding out what called a Ruby method

A quick way to understand what is calling your code using the caller method