Platform security documentation

As part of a larger effort to unify disparate parts of the Foundry platform, I completed work to clarify and communicate complex security concepts. The larger effort involved working with teams across the product group to help clarify platform concepts and primitives. What is shown below is a sample of that work – the work we did to document the platform’s security model.

At the time of this project, significant changes to the security model were being introduced in various backend services. But little thought had been given to how these changes would impact the user experience. What’s more, the teams working on security were in different offices and were misaligned on how parts of the security model were supposed to work. Thus began the effort to help clarify and communicate the security model.

We began by spending time at the whiteboard with Foundry’s chief architect, as well as other senior engineers, to deeply understand the security model. Shown below are a sample of those whiteboards.

Through many whiteboarding sessions and iterations, we clarified how the new security model would work. In particular, we identified the primitive concepts that users would interact with to understand security. For example, while a particular backend service handled permissions, users experienced security by interacting with projects, roles, and security markings.

A key part of the work was explaining complex ideas using pictures. Below are several of the drawings I created to illustrate how projects work.

Additionally, well-written explanations were important to tell the complete story. Here is a draft of the documentation I helped write for projects, which incorporated the drawings.

As part of the larger effort, we realized that we needed a definitive resource for developers to reference to understand these different, interrelated concepts. This led to the creation of a Foundry developer website.

Shown below is the Foundry developer website with the final documentation for Projects.

There was much more to this work than shown here (ask me about it!). I knew the security work was successful when, months later, the Engineering Group Lead of the security team (which had been formed part-way through our work) used the drawings from the documentation for a tech talk explaining the security model to the entire product group.