Steve Kaliski

Engineering Values as Documentation

As engineers we think about documentation quite a bit.

  • The README in our repositories.
  • The comments we leave in our code.
  • The wiki for a service we operate.

The intent with any documentation is to help a new engineer understand how something works, with the hope that they can quickly use the system. But just as important, so that they can improve the system.

Documentation becomes increasingly important as more APIs and systems are introduced.

For many companies, documentation efforts are equally applied to a teams Engineering Values. Here are some examples:

This type of documentation is critically important — a new engineer can quickly understand how the team (The system) works: how do members interact? how are decisions made? what is and isn’t important? how does one grow in the team?

Every team is unique and though there may be familiar parts, each requires its own documentation. This isn’t a task for an individual nor is it a task for a third party. Everyone on a team is a contributor and is responsible for helping document the team. Asana even had team members write descriptions of what each value means.

I hope to continue to see teams invest in this! If you or your team are working on documenting your values, I’d love to hear from you!

Steve Kaliski

Hey! I am Steve Kaliski, an engineer and entreprenuer based in NYC. I love building tools to help people do their jobs.