Not Learning the Lingo: How a Bad Performance Review Gave Birth to a New Start Up
Part Two of Two
Part one defined the problem of unscalable software engineering and shared an insight into how to solve it. Part two offers a solution based on that insight:
World, meet Lingo, Lingo meet world: www.lingo.reviews. This post launches the open sourcing of Lingo.
Lingo is a heuristic tool to scale up engineering. Lingo ensures code conforms to best practices while educating contributors and keeping the map and territory of a product in sync. That is, Lingo manages the quality of a product as the project scales up.
Map and Territory
Lingo generates the relevant part of the map for the context the engineer is working in:
The map and territory are, at last, working together to guide the engineer to a correct solution: a solution which respects and leverages the best practices of the team and product. The workers’ guidelines in the above example are from William Reade’s emails in part one. If the engineer neglects to follow them, Lingo will highlight where the code has fallen out of sync: the documentation itself reviews the code.
If Juju used Lingo, no worker using state.State would have been able to land. The ongoing struggle to manually align everyone’s map of the product and the territory of the code would not have been needed.
The Tenet
In the above example, each guideline and its corresponding review comment is generated from a tenet. Each tenet captures a piece of product specific best practice.
Lingo is the underlying process orchestrating all tenets. With tenets, Lingo manages the integrity and quality of a product as it scales up. The tenet itself is an artefact. The documentation and code analysis for each need to be written. But this artefact becomes the one source of truth which, in combination with other tenets, enables Lingo to generate the many more transitory and contextual artefacts needed to share knowledge across a team.
A fully functional tenet can be written in under 40 lines of code. Lingo uses GRPC to talk to the tenets. RPC APIs can be generated for all the languages GRPC supports. Lingo currently has best support for Go as Canonical is piloting Lingo for Juju, which is written in Go. The burgeoning Lingo community has already begun to contribute support for Python.
With Lingo, the tenet is a force multiplier. Depending on the prevalence and consequence of the issue it targets, the tenet is an exponential investment in improved velocity and quality. The larger the project, the larger the pay-off. Each tenet can be published and used by anyone with the Lingo tool. Thus smaller projects with less resources can benefit from the investment of larger projects. With luck, the Lingo community will grow and with it the number of published tenets: best practices could then be imported and shared across the industry.
The Applicability of Tenets
The applicability of tenets, in the traditional sense, has always been a gradient from “this doesn’t seem right” to “this certainty isn’t right”. At one end of the spectrum you have your linters and formatters. At the other you have the, harder to define, human appreciation of quality — or lack thereof. In between, there is a large portion of codifiable judgement: not black and white, but also not without definition.
Tenets encode this gradient. A tenet can give context to a raised issue with custom metrics and tags. This context can then be used to generate relevant artefacts for the team: for example, a techdebt burn-down chart or kanban issues by tag.
Lingo’s goal is not to automate reviews with the aim of catching issues. Lingo has a loftier goal than this. The review is where the maps meet in the territory:
- the reviewer’s map, expressed in comments
- the engineer’s map, expressed in new code and
- the historical map, expressed in existing code.
By automating that large portion of codifiable judgement, Lingo uses the review to tap into the knowledge flow of a project and ensure that the correct knowledge is being shared and applied. Lingo’s ultimate goal is to orchestrate all artefacts in the software development process and ensure each contribution is perfectly aligned with them. Lingo is to be the caretaker of quality at scale.
Lingo as a Mentor
Reviews aim to educate the contributor and do so in a way that reflects a human review. To this end, a tenet author can define contextual comments. For example, the first time an issue is found, the comment explains the issue in detail. The second comment explains it with less detail in a different way and the third simply refers to the issue — which has already been explained and defined. In the above example, even if there are one hundred files without the correct copyright, Lingo will only make three comments.
Lingo is a personality neutraliser. Many of the reviews I have seen and received are late, rude and exasperated. The reviewer is overwhelmed and exhausted with fire-fighting the same issues again and again which may be new to the contributor, but not to them.
If we think of software engineering itself as a system, this is the system panicking. No matter how many ‘o’s you put on a “nooooooooo!!” comment (yes, that is a real comment I have received in a review) the possibility that the same issue will appear in the next PR is still not being handled (it also does nothing to attract and retain external contributors).
With Lingo, we pre-empt and handle the error. We don’t panic after the fact. No matter how many times I make the same mistake, Lingo will politely and patiently point it out to me. In doing so, Lingo will lead me to consider the context I am working in and to leverage the patterns and utilities in that context — resulting in a better thought out solution.
Needless to say, this alleviates a considerable amount of work from the lead engineers. By the time the PR gets to them, Lingo will have cleared the debris allowing them to focus on the subtler issues.
Egos and Engineering
Software engineering is a team sport which also calls upon the creative problem solving of each individual. There is a tension here. When working collaboratively on a large project, it is rare that you will work on a problem without pre-existing context. But, as engineers, we can build our own solutions and make our own patterns. In doing this, there is a danger that we are insulating ourselves from existing solutions and undermining the coherence of the product.
With the traditional review, the engineer is confronted with the “correct way” after they have developed their own way. When the correct way is informally defined by historical decisions it is hard to distinguish it from the opinion of the reviewer. I have seen untold hours lost to arguments in the resulting tension.
Lingo forces a team to agree on and define the core tenets of the team, product and components, up front. When code falls out of sync, there is no ego to battle with on the other end of the review, equally there is no judgement to feel ashamed of or defend against.
With Lingo, the tension between the individual’s way and the “correct way” is never allowed to grow: it is nipped in the bud. The context will literally shout out to the engineer and say, “Hey, you should/shouldn’t be doing this”. That will lead the engineer to search for a solution with the context.
The Vision
Today, Lingo offers automated reviews and situational documentation. While this is what Lingo does, it should not define what Lingo is.
Lingo is the underlying process which manages the quality of a product as it scales up. The quality of a product can be defined by the degree to which: what it should be, aligns with what it is. That is, how closely its map and territory match. This is the core concern of Lingo. All features and services Lingo offers will be aligned by the mission to manage quality at scale.
Thank You
To everyone who motivated me and shared their time and wisdom with me to get to this point, THANK YOU:
Plug and Play: Michael Hoch, Cirrus Shakeri, Ron Gentile, Raj Singh and Bow Rodgers.
You took the time to learn about Lingo, saw its value and helped me refine its value proposition. Thank you.
The Sages of San Francisco: Burću Dogan (Google), Soloman Hykes (Docker), James Burns (Twillio) and Michael Grinich (Nylas).
During my time in San Francisco you each opened doors that would have otherwise been locked to me and gave invaluable advice. Thank you.
All of Juju Core, but especially: Alexis Bruemmer and Mark Ramm, William Reade, Tim (and Rachel) Penhey, David Cheney, Menno Smiths, Katherine Cox-Buday and Nate Finch.
You have each played key roles without which Lingo would not be what it is today — or here at all. Thank you.
Awesome individuals: Matthew Cook, Wayne Witzel, Nik Wakelin, Umair Akeel and Lance Wiggs.
Thank you for your support and being so awesome :)
My Family: I don’t say it often enough but you are my backbone. Thank you.
