Lightstep from ServiceNow Logo





Lightstep from ServiceNow Logo
< all blogs

How We Write Code at Lightstep: Lab Notebooks

Many engineering teams create some form of a Design Document in the early stages of a new project. These documents are useful because they help the team debate and arrive at a high-level architecture and implementation plan to move forward with.

At Lightstep we do things a bit differently. Rather than Design Documents, we’ve created “Lab Notebooks.”

Lab Notebooks vs. Design Documents

One common problem with design documents is that they are static. Let’s face it, the software we ship rarely is an exact implementation of the thing we initially designed. This isn’t a failure, but rather a reality of developing software for a business that is constantly changing.

Over the lifecycle of a project, there are countless decisions, big and small, that need to be made in order to drive the project forward. These decisions are incredibly important in explaining the design of a system but often happen at a whiteboard and are then forgotten.

Lab Notebooks allow us to be much more flexible in delivering on multiple projects across many teams — at the same time.

How Lab Notebooks Work

A lab notebook replaces an engineering design doc (as well as possibly other docs). It is not meant to serve as documentation of the end result of a project (for example, product documentation, oncall training), but rather it captures the evolution of a project throughout its different stages. It records changes in scope, shifts in priority, trade-offs considered, and decisions made.

You can find a more complete explanation of what a Lab Notebook is in our Lab Notebook templateLab Notebook template:

Commander’s Intent

  • Encourage incremental approaches to project design and implementation

  • Include stakeholders and experts from across the company in the discussion without a rigid sign-off process

  • Support retrospectives and postmortems by recording important decisions for later

A successful project lab notebook accomplishes these goals by:

  1. Recording questions, hypotheses, assumptions, experiments, and important decisions related to the project as they occur, as well as the results of these experiments and decisions

  2. Serving as a log of interactions with – and future questions for – people that are not members of the project

  3. Acting as a resource for future team members (as well as our future selves) to help us recall and understand why we built the things we did

Feel free to use this template with your team! (And let us know how it goes!)

How Lab Notebooks Have Helped Our Team

We’ve found the introduction of Lab Notebooks to be really helpful in managing the multiple in-flight projects that we have going on. Documenting decisions is both cathartic, and useful. Rather than having to rehash the same conversation over and over, you can point to a specific entry in the Lab Notebook that includes a discussion about the tradeoffs made and the reason for the decision. Having a written “history” of a project is also helpful for onboarding new team members on a project. They can read through the Lab Notebook and follow the project’s trajectory from inception to the present — providing a strong understanding of the project in its context.

Why This Matters

Thinking about the design of your system holistically in the early stages of the project helps to de-risk the project overall because many “gotchas” can be caught early — particularly when the document is socialized across the entire engineering organization.

In addition to getting valuable input from people with different domain specializations, you also get the benefit of increasing the awareness of your project across the organization. This can often lead to synergies with other teams that would be hard to identify otherwise.

With Lab Notebooks, we gain the ability to look at design over time. Rather than creating static documents, we come closer to recording the full story. In a way, Lab Notebooks can be the telemetry for your project; important events are logged and you get an end to end trace.

Interested in joining our team? See our open positions herehere.

August 25, 2019
4 min read
Lightstep Culture

Share this article

About the author

Julian Griggs

Julian Griggs

Read moreRead more

My Time At DevOps Summer Camp: Deserted Island DevOps 2022 Recap

Ana Margarita Medina | Sep 29, 2022

Recap of Ana Margarita Medina's experience at Deserted Island DevOps conference

Learn moreLearn more

The DevOps Conference Everyone Needs Right Now

Katy Farmer | Apr 22, 2020

This is not your typical virtual conference. Deserted Island DevOps is a virtual DevOps conference that takes place wholly in Animal Crossing with nearly 500 attendees and a full list of speakers. Register now to join the fun!

Learn moreLearn more

Lightstep Wins a Best Place to Work in the Bay Area

Austen Yueh | May 1, 2019

We’re excited to announce that we are a winner of the 2019 Bay Area Best Places to Work, an awards program presented the San Francisco Business Times and Silicon Valley Business Journal.

Learn moreLearn more

Lightstep sounds like a lovely idea

Monitoring and observability for the world’s most reliable systems