From fac06b2804bf6357a3f25da71a9a89096fcf34de Mon Sep 17 00:00:00 2001 From: pablo Date: Tue, 7 Dec 2021 17:20:31 +0100 Subject: [PATCH] Added post. --- posts/negotiate-contracts-with-git/content.md | 115 ++++++++++++++++++ posts/negotiate-contracts-with-git/meta.yaml | 7 ++ 2 files changed, 122 insertions(+) create mode 100644 posts/negotiate-contracts-with-git/content.md create mode 100644 posts/negotiate-contracts-with-git/meta.yaml diff --git a/posts/negotiate-contracts-with-git/content.md b/posts/negotiate-contracts-with-git/content.md new file mode 100644 index 0000000..a451a86 --- /dev/null +++ b/posts/negotiate-contracts-with-git/content.md @@ -0,0 +1,115 @@ +A few years ago, I was put in charge of a project to develop a web application. The technical details are mostly not +relevant, but I should note that we were planning on using some data formats and Javascript modules that are not that +mainstream ([in case you are curious](https://cesium.com/platform/cesiumjs/)). Because of this, we needed some +specialized hands that knew their stuff on this not so popular domain. Luckily, this small consulting firm that my +company had already worked with in the past had this kind of knowledge. So, I was tasked with negotiating a contract +with them to use their services to develop the web app. + +I was given some constraints: budget, a few intellectual property policies from our side, some expectations on support +requirements after the app was finished, etc. With that and some support from my legal department, we made an initial +draft. And then, we entered a pretty standard negotiation cycle which ended after a couple of weeks with both parties +happy with the final contract. + +So what? + +The information flow. The communication. The way the contract and its changes were handled during those two weeks. +_Terrible_. It was a complete mess. + +Let me describe for you the roles that had a say during the negotiation and how the negotiation cycle worked: + +- My company, BigCorp Inc: + - Me (aka The Rabbit): I was moving information all over the place and pushing people to do their work because I + needed the contract signed to do my thing. + - Big Boss: he put the constraints in place, which I translated into more detailed clauses in our contract. He had the + final say in some important topics. + - Head of Legal: provided creative ideas into what was and was not possible and reasonable from a legal point of view. + Oversaw everything to make sure we did not Screw-Up™. +- Our providers, SmallConsulting LLC: + - Their Rabbit: just like me, but on the other side of trench. + - Their Big Boss: idem. + +And then the cycle looked roughly like that: + +1. I proposed a change in some clause in the contract. + +2. Their Rabbit and I wrote it down to ensure we were both talking about the same thing. + +3. Their Rabbit would go to Their Big Boss to gather his feedback. + +4. Their Rabbit would come with either approval (end of story) or some sort of counteroffer. + +5. I would then play my rabbit role and go to Our Big Boss to gather his feedback, leading to approval (end of story) or + some sort of counteroffer. + +6. If I got a counteroffer, he would ask me to double-check with Our Head of Legal to avoid a Screw-Up™. + +7. Our Head of Legal would either: + - Give a plain OK. + - Propose some subtle changes that didn't really change the bottom line of the content. + - Say that was not OK and would lead to a Screw-Up™, which meant taking a step back towards Our Big Boss. + +8. Eventually, both Our Big Boss and Our Head of Legal would be ok with the counteroffer, and then I would take it to Their + Rabbit. + +9. The loop continued in this fashion until an agreement was made, and the text was committed in the document. + +Luckily, not every detail had to go through all of these steps. But quite a few had to. + +So, what is your guess on what tool was used to manage all of this? That's right, emails and a Word file. Well, not +strictly _one_ word file, but rather a thousand different versions of it flying around in a freestyle, anarchic way. + +At the time, I didn't think much about the choice of tooling. It was obvious that the combination of email and Word +files was a confusing, time-wasting, error-prone mess. And it was also the reason that the rabbit role existed at all. +But, hey, if it wasn't that, then what, right? + +Well, a few years later and with a few more scars, a better tool for this comes across as obvious in my mind: git and +plain text. + +__A contract? With git?__ Well, why not. Just make it a markdown file instead of Word document and put it into a git +repo. I see quite a few advantages to it: + +- A contract like the one we had to do has no visual requirement that can't be satisfied with markdown and any decent + rendering solution to PDF like (pandoc)[https://pandoc.org/]. So, no time wasted on how things look like, which in my + opinion is completely irrelevant in these cases since contracts are usually doomed to be ugly. +- Diffs! Spotting changes would be trivial. What have we changed today? How was the contract looking a week ago? What + have I missed? Diff, diff, diff and you are done. +- Just in the same way we use branches and PRs for code, each individual changed proposed by one of the parties could + have been an individual PR. That would provide a single space where that specific content could easily be discussed + among all the stakeholders (without me having to play the rabbit role) and the typical PR approval systems would make + sure no changes were introduced in a sneaky way. Plus, the reasoning and negotiating that led to some change to be + included in the contract would also be recorded, which can help in case you want to remember how an agreement was + reached. +- In the same way we build changelogs when releasing software, we could also use the PRs to build contract changelogs + whenever we would feel like making a named or numbered version out of it. + +And I am sure there are more that I am missing. + +So, why are things not done this way? Two big reasons come to mind: + +- Non-coders don't know git. Simple, but nevertheless a monster roadblock for the adoption of git despite its advantages. + Short-term, this is hard to deal with, but maybe someone should consider knocking on the door of Law School and + convincing them that git is completely relevant to their profession so that one day this stops being an issue. There + are also online SaaS web-apps that seem to provide user-friendly markdown+version-control features, but I haven't + found one that feels simple enough for a pure non-technical user to pick up instantly. I guess the whole + commits/branches/merges/etc mindset will always + [leak](https://www.joelonsoftware.com/2002/11/11/the-law-of-leaky-abstractions/) no matter how much you try to hide it + behind nice interfaces. +- Some roles in these negotiations benefit from things being a mess, and thus are not interested in making things any + simpler or clear. This ranges from business people that will try to use the confusion to sneak in stuff in the + contract(_good fishing in troubled waters_), to legal profiles that partly justify their existence by making things + overly complicated. Or they just charge you by the hour. + +Hopefully, version control will find its way out of the software realm and will improve the life of many other areas, +like law. Those of us who are familiar with it have a great chance to help others benefit from this wonderful tool that +has served us so well. + +I also have the intuition that the domain of law could benefit from many other spill-overs from the software domain. But +I'll leave that for another post. + +And a fun story to finish: once we finally managed to reach an agreement, I sent a physical copy of the contract to +SmallConsulting LLC so they would sign it. Then got a call from them. They told me that our NIF code in the contract (that's +the Spanish tax ID for a company) was wrong. Not a small typo, but rather that the NIF code was of another company that +had absolutely nothing to do with us. They didn't even have to check it in any database: the NIF we had written started +with B, which was not possible since we were a public company, and in Spain that means our NIF begins with A. + +If only the contract had been a JSON file and someone would have built a validation script... diff --git a/posts/negotiate-contracts-with-git/meta.yaml b/posts/negotiate-contracts-with-git/meta.yaml new file mode 100644 index 0000000..2df12d6 --- /dev/null +++ b/posts/negotiate-contracts-with-git/meta.yaml @@ -0,0 +1,7 @@ +title: Negotiate contracts with git +date: 2021-11-16 22:32:00 +category: stories +tags: legal,git,version control,stories,negotiation +slug: negotiate-contracts-with-git +authors: Pablo +summary: A story about legal text, people and git. \ No newline at end of file