As we embarked on Notary v2, we needed to incorporate experts from multiple backgrounds, experiences and skillsets. The various perspectives also brought historical biases that made it difficult to communicate, particularly as there was a lot of feelings around Notary v1. It wasn’t long before we had challenges in how we communicated perspectives, attempting to get everyone on the same page. It didn’t mean everyone would agree, but at least we agreed to what we were talking about.
The typical Open Source model for authoring specs is to “write it down”. Create a pull request on some markdown so all can review.
The problem isn’t in the writing, it’s in the reading.
Assuming we actually read the whole thing, as opposed to the scan and perceive model, we all read interpreting the words with our own experiences and biases.
- 10 people that read the same book, tend to have 10 different perspectives on the story.
- 10 people that watch the same movie, have the same experience, although they may not all like it.
When we read, we interpret the words with our unique historical context and biases for the meaning of those words, or even the technical jargon. Our brains fill in reactions, emotions and perceptions for what we’re reading, based on our experiences.
When we watch a movie, the visuals are provided, the soundtrack evicts emotions. We’re fed the entire experience to digest. This is likely why many prefer to run and read the code, as opposed to read the spec. They want to “experience the thing”.
We weren’t ready to produce a movie, so how would we fill in the gaps to enlist the expertise on a common goal? Let’s build a prototype.
There are many approaches to building prototypes. Some approaches cater to simple projects, while others are better at supporting complex projects.
Notary v2 is goaled at securing a complex e2e secure supply chain workflow.
This will involve many subject matter experts (SMEs) and various projects to engage. Since no one person or group has a concrete blueprint for what and how we would build this e2e solution, we can be stalled with gaps of communication and differing views.
Building Complex Software
Building a complex solution is not unique to Notary v2. We will bring SMEs from various areas, each with their own views, and we will continue to evolve the design until we’re ready to execute.
In software, there are many models, including waterfall and iterative. However, within the iterative, there are at least two additional approaches:
- Build and iterate with constant changes, churn and frustration to those dependent on the outcome
- Consumers of the effort can get lost with complaints of instability
- Build a prototype, learn, toss, build the real thing, with a reasonable amount of iterations
- Consumers clearly see this as a prototype, monitor, provide feedback and await the outcome while the SMEs work out all the details
Prototyping Other Complex Project Types
In construction, we must bring together various designers, architects and trades:
- Designers provide sketches to quickly iterate ideas, narrowing in a common goal
- Architects provide detailed blueprints, with layered designs from various trades, incorporating their expertise
- Grading contractors – sculpting the ground by which the property will reside
- Foundation contractors – providing a solid foundation for the structure, including environmental impact and risk (earthquakes, floods, …)
- Framing contractors – accounting for the various contractors that must fit all internals that make a house a home
- HVAC contractors – have large spaces to heat and cool, requiring the framers to account for the plenums and returns
- Plumbing contractors – that may provide detailed design for that fancy glassless shower and constant hot water, while being able to route supply and drain lines around the HVAC systems
- Electrical contractors – needing to place the switches and outlet in all the right areas you blindly reach for
Each trade may not know the details of the other trades, but they know they need to work together. The plumbers and electrician must work around the HVAC systems, the grading contractors must provide a solid footing, with water runoff for the foundation to be stable.
While auto-cad and 3D programs allow users to visualize the design, we often start with a sketch for where to start the detailed design. For complex designs, modeling is often used to see how the design will actually work. Can you really extend the patio that far out without it bouncing? Or how long and how much water will it take to get hot water to the shower? As productive as auto-cad and 3D programs are, it’s still complex and expensive to design a building from scratch. Which is why so many buildings are based on existing proven templates. To build something new, depending on the complexity of the problem, we may need to sketch and model a design before proceeding to detailed blueprints.
The Creative Work of Antoni Gaudí
Antoni Gaudí is famously known for his amazingly creative works in Barcelona. The Sagrada Famila was a departure from the massive piers and buttress designs. Gaudí wanted a more natural look, which had no existing templates to work from. Gaudí sketched and modeled many times to work out the intricate details for the various trades to work together. To design natural arches and vaults, Gaudí created an inverted model using small bags of birdshot and string. It’s through this sketch, model, design, execute approach that Gaudí was able to enlist the creative skills of various trades to eventually complete the Sagrada Famila.
Sketch, prototype, experiment, iterate
The different views and interaction of the different trades is equivalent to the different views and interaction we need between the different SMEs and project owners for Notary v2.
- Key Management folks need to figure out where they should engage, providing input on how keys should be managed
- Key Vault solutions must understand where they plug in their key vault provider for each registry
- Policy Management folks need to understand what content they can pull from a registry, and how they should trust it to make policy decisions
- The Update Framework folks must understand where they can plug in their metadata to assure the content is secured from rollbacks
- The folks working on the secure software supply chain efforts must understand the registry workflows and what they must account for
- The registry vendors must understand the implications for the changes they must make to support Notary v2
Just as the public provides feedback on public works like the Sagrada Familia, Notary v2 users need something to view for providing feedback.
To facilitate the e2e workflows, we’ve started with the following:
- Sketch an e2e workflow, supporting the Notary v2 scenarios
- Prototype various components of the e2e workflow including
- Prototype an nv2 client for signing and verifying artifacts
- Instance a registry that implements APIs required to store and serve signatures and verification objects
- A key vault solution for storing signing keys
- A SBoM document, used for making policy decisions
- A Policy Manager, used to make policy decisions
- A container hosting solution to deploy secured containers
- Create an environment to experiment with the e2e workflows
- Iterate, with a set of milestones each team will work towards
As we get to a point where we feel comfortable with the e2e design, that accounts for the Notary v2 scenarios, balancing the security and usability goals, we can move to a spec (blueprint) for building out the final versions of each component.
A Work in Progress
If you follow the history of the Sagrada Familia, you’ll learn:
- The project started March 19, 1882 – yes, 1882
- Gaudi died in 1926, with less than 25% complete
- The Spanish civil war of 1936 interrupted the project
- Gaudí’s models and workshop were destroyed during the war by Catalan anarchists, while many models were recovered or reconstructed
- The project is funded through donations, with no governmental or corporate involvement
- The city offered fund and complete the project for the 1992 Barcelona Olympic Games
As of August 2020, the project is near, but not quite at completion:
The Notary v2 work is also a work in progress.
You can track the Notary v2 progress here on GitHub. While we work through the COVID-19 pandemic, we hope we’ll complete with fewer challenges and less than 138 years.