Blog

The brief guide to MSCD 5

Luis Villa1 Comment

My primary goal when trying to improve a contract’s drafting is not “plain english”. The goal is simplicity, clarity, and consistency, because complexity is a source of errors. As a pleasant side-effect, contracts drafted with rigorous attention to consistency and clarity are generally shorter, and almost always much easier to read.

Ken Adam’s Manual of Style for Contract Drafting has helped me immeasurably in reaching that primary goal, both by teaching me habits of mind and by being a reference for better linguistic structures.

But it’s also hefty.

So I prepared this mini-guide to MSCD for an outside counsel: it’s what I recommend first-timers read, skim, and skip. I share it here in hopes it may be useful for others.

All section references are to the Fifth Edition, but at least at the chapter level most should apply to earlier versions as well.

MSCD core concepts

These are the most impactful sections of MSCD.

Introduction

If you are confused about why I recommend the book, read “About this manual”, “Traditional Contract Language is Dysfunctional”, and “Excuses for Sticking With Traditional Contract Language”. Skip or skim the rest.

Ch. 1: Characteristics of Optimal Contract Language; Ch. 17: Drafting as Writing

These can be skimmed, since in some sense most of it will be obvious to anyone who has given any thought to better contract language. But both are good, and brief, and explain (in part) why traditional drafting is so bad. So if you find yourself confused by something in other chapters, come back to these two—they may help explain things.

While reading, I particularly recommend these sections, which have had the biggest impact on my personal drafting style and are, in my experience, the biggest red flags for errors that stem from bad “traditional” drafting:

  • “Contract Language Shouldn’t Be Legalistic” (1.7-1.28)
  • “Contract Language Should Express Ideas without Redundancy” (1.35-1.56)
  • “Contract Language Should Be Consistent” (1.57-1.60)

Ch. 2: Front of the Contract; Ch. 5: Back of the Contract

In my practice area, the front and back matter are not usually the source of critical errors, so I do not religiously follow these sections. However, I find that attention to detail on these topics is both a good introduction to MSCD’s style of thinking, and (when I do them in a contract) help put me in a rigorous frame of mind for the rest of the document. So these chapters are worth skimming and then consistently using as a reference.

If you are pressed for time, 95% of chapter 2’s value can be obtained by:

  • reading 2.129-2.150, Recitals. Once you get used to improving the drafting of the recitals, it sets a good tone for the rest of the document.
  • reading 2.159-2.164, Wording of the lead-in. Understanding, and sticking with, Ken’s recommended use of “agree” here sets up Ch. 3’s critical “categories of contract language”.
  • skimming Samples 1 and 2, and Appendix A’s front matter, to get the flavor of the kinds of improvements that can be made to most contracts.

Ch. 5 is similar—just skim the back matter of Appendix A, then refer to the samples in the chapter for models.

Ch. 3: Categories of Contract Language

If you only read one chapter, read this one.

This chapter is the core of MSCD’s style of thought: the core of clear and correct drafting is that different parts of contracts do different things, and you should rigorous using specific language to implement each of those things.

You can do a lot to improve a contract simply by looking at each table in this section, reading the relevant section to understand the tables, and cleaning up every reference in a contract from the table’s disfavored language to the favored language. Doing this consistently across the entire contract will force rewrites that leave the resulting language much clearer, more precise, and more accurate.

Two words discussed in this chapter are particular warning signs for me when I see them misused in a contract: “shall” (particularly 3.115-3.132 and Table 2) and “agrees” (3.27-3.30). Again, simply cleaning these up is a great way to do a “first pass” edit of a document—doing this helps you think about what each clause of a contract is actually trying to do, and often leads to more correct, more readable drafting.

Ch. 13: Selected Usages

This is a reference section, not something to read end-to-end. But it’s invaluable. When you find something that “feels wrong” in a contract, you’ll often be able to come to this section and find a much better, clearer way to state it. You may have to rewrite things substantially, but you’ll have a more logically consistent, consistent, correct, clearly-readable document when you’re done.

I suggest skimming the table of contents, and then reading a few examples to give you the flavor of it. A couple of my favorites:

  • For the Avoidance of Doubt: 13.312-319
  • “Including”—long, but a great analysis of the complexity and nuances of a single word: 13.359-407

Ch. 14: Numbers

Read the brief part on “Words or Digits” to learn why there should be zero(o) instances of number(numeral). Skip or skim the rest.

Advanced Drafting to Reduce Ambiguity

These chapters are useful primarily for the most complex drafting problems. I tend to do a “first pass” edit based on the “core concepts” chapters I identified previously.

If that first edit pass identifies a particularly complex/problematic section, then the concepts in these chapters can be quite helpful in making the challenging contract sections more correct.

  • Ch. 7: Sources of Uncertain Meaning: 95% of the value of this chapter is one concept: the distinction between ambiguity (bad, unintentional, should be eliminated) and vagueness (intentional, may be strategic, must be deployed carefully).
  • Ch. 11: Ambiguity of the Part v. The Whole: most useful in commercial contracts where it’s important to be precise about what is being sold (or not).
  • Ch. 12: Syntactic Ambiguity: a collection of techniques that are frequently useful in deconstructing, and then reconstructing, extremely long or complex sentences.

Interesting but not useful (to me/my practice)

These chapters are intellectually interesting but I have not found them to be particularly high-impact on my practice. Might be different for your practice!

Ch. 6: Defined Terms

I do not find definitions to be a significant source of problems, as a practical matter, so don’t find this chapter hugely valuable.

However, there are a few sections that cover errors that I find frequently, so are more useful than the rest:

  • “Be Consistent” (6.8-6.13)
  • “stuffed definitions” (6.49-58)
  • Mistakes: 6.110-6.122

I don’t usually follow the advice of “where to put the definition section” (6.96-6.98), but I think it’s at least worth trying in many documents.

Other interesting-but-less-useful-to-me chapters

These chapters are all interesting for drafting nerds, and may be relevant to some practices, but not frequently an issue for me.

  • Ch. 8: Reasonable Efforts
  • Ch. 9: Materiality
  • Ch. 18: Amendments; Ch. 19 Letter Agreements

Neither interesting nor useful (to me/my practice)

I mostly ignore these—they’re not wrong but the bang-for-buck of rewriting with them in mind is pretty low, in my experience.

Ch. 4: Layout; Ch. 16 Typography

I tend to rely on Butterick’s Typography for Lawyers for these topics.

Ch. 10: Time

Suspect most relevant for certain types of commercial contracts where extreme specificity about time (delivery, etc.) are common sources of disputes.

Ch. 15: Internal rules of interpretation

Have never seen one of these in the wild that I can recall.

Announcing the Upstream podcast

Luis Villa2 Comments

Open is 1️⃣ all over and 2️⃣ really interesting and yet 3️⃣ there’s not enough media that takes it seriously as a cultural phenomenon, growing out of software but now going well beyond that.

And so, announcement: I’m trying to fill that hole a little bit myself. Tidelift’s new Upstream podcast, which I’m hosting, will:

  1. Pull from across open, not just from software. That’s not because software is bad or uninteresting, but because it’s the best-covered and best-networked of the many opens. So I hope to help create some bridges with the podcast. Tech will definitely come up—but it’ll be in service to the people and communities building things.
  2. Bring interesting people together. I like interview-style podcasts with guests who have related but distinct interests—and the magic is their interaction. So that’s what we’ll be aiming for here. Personal goal: two guests who find each other so interesting that they schedule coffee after the recording. Happened once so far!
  3. Be, ultimately, optimistic. It’s very easy, especially for experienced open folks, to get cynical or burnt out. I hope that this podcast can talk frankly about those challenges—but also be a recharge for those who’ve forgotten why open can be so full of hope and joy for the future.

So far I’ve recorded on:

  • The near past (crypto?) and near future (machine learning?) of open, with Molly White of Web 3 Is Going Great and Stefano Maffuli of the Open Source Initiative. Get it here! (Transcripts coming soon…)
  • The joy of open. At Tidelift, we often focus on the frustrating parts of open, like maintainer burnout, so I wanted to refresh with a talk about how open can be fun. Guests are Annie Rauwerda of the amazing Depths of Wikipedia, and Sumana Harihareswara—who among many other things, has performed plays and done standup about open software. Will release this tomorrow!
  • The impact of open on engineering culture, particularly at the intersection of our massively complex technology stacks, our tools, and our people. But we are often so focused on how culture impacts tech (the other way around) that we overlook this. I brought on Kellan Elliot-McCrea of Flickr, Etsy, and Adobe, and Adam Jacob of Chef and the forthcoming System Initiative to talk about those challenges—and opportunities.
  • The relationship of open to climate and disasters. To talk about how open intersects with some of the most pressing challenges of our time, I talked with Monica Granados, who works on climate at Creative Commons, and Heather Leson, who does digital innovation — including open — at the IFRC’s Solferino Academy. I learned a ton from this one—so excited to share it out in a few weeks.

Future episodes are still in the works, but some topics I’m hoping to cover include:

  • open and regulation: what is happening in Brussels and DC, anyway? Think of this as a follow-up to Tidelift’s posts on the Cyber Resilience Act.
  • open and water: how does open’s thinking on the commons help us think about water, and vice-versa?
  • open and ethics: if we’re not technolibertarians, what are we anyway?

I’m very open to suggestions! Let me know if there’s anyone interesting I should be talking to, or topics you want to learn more about.

We’ll be announcing future episodes through the normal Places Where You Get Your Podcasts and the Tidelift website.

Notes on using Freedom to block digital distractions

Luis Villa1 Comment
“Escape” by Metaphox is licensed under CC BY 2.0, via openverse.

I’ve been using freedom.to more or less since it launched. I was recently asked by someone how I use it, and since it didn’t fit in the text box on that platform, here’s a mid-ish-long set of notes on how I use it.

  • Everywhere: It’s on all my devices, no exceptions—iPad, phone, desktop work computer.
  • Scheduled sessions: I use what Freedom calls “sessions” to schedule blocks of time that block out distracting sites. My current blocked sessions are:
    • Working hours: Mostly self-explanatory, starts an hour after school drop-off so I can do some messing around or necessary social stuff before work. Also includes a lunch break every day (actually implemented as two sessions), though unfortunately that isn’t synced to my calendar so sometimes I am unblocked while working and then blocked during my actual lunch.
    • Morning self-care block: There’s an hour in the morning (before family breakfast) that blocks social plus work stuff. Ideal (not always respected) is that I should be using this time mostly for fitness or meditation, not the device. Am sorely tempted to replace this with just keeping the device well away (probably upstairs) and using an Apple TV device for fitness/meditation.
    • Evening family block: From roughly when my son gets home to his bedtime, blocks primarily social. Can still do some work if sorely needed but try to avoid social during that time.
  • Add sites freely: If I’m at all tempted by a site, I add it to the Blocklist. Better to overblock than underblock. (I understand why it probably can’t, but it’d be neat if Freedom monitored web usage, said “I notice that you’ve visited this more than X times today, would you like to block it?” Bonus for: “and add its RSS feed to your feed reader?”) In particular, I mass block sports, social, and news sites—you simply don’t need those things most of the time.

Because of my recent participation in the Mind Over Tech Accelerator trainings (which I cannot endorse enough if you struggle with digital focus!), I’ve made some recent experimental changes to my freedom use. I’m not sure yet if these will stick long-term:

  • Breakfast-time session: I’m experimenting with blocking more things during my family breakfast (6:50-7:50) and just relying on voice control or a shared family kitchen iPad for the few things I need to do during that block. In other words, using Freedom to force me not to touch my own devices during this block of family time.
  • Pomodoro: I’ve been experimenting with Forest for pomodoro timing, but I do wonder if I can do Freedom instead.
  • Apps: Freedom just added the ability to block apps, so I don’t use this yet. Not sure if I will, because most of the things that suck my time can be dealt with by blocking their network connections.

My challenges with Freedom (suggestions welcome!):

  • Reliability: Because Freedom is inherently doing something that the operating system doesn’t love (interfering with your use of the device!) it sometimes stops working, and you have to re-engage it. Which is fine, unless… I’m doing something that it wants to block. For example, during a recent trip, it disengaged and it was more convenient for various reasons not to turn it back on. Which was fine except now I’m back home, I should turn it back on, and I’m… not. (I’ll do it right after I post this! Probably!)
  • Social: My work does sometimes genuinely require use of social, which is hard if you’ve… blocked all social with Freedom. I don’t have a great solution to this, but people are mostly reasonable if you say “actually, I have social blocked on this machine, is it OK if [I do it later, you screenshot it, etc.]”
  • Location: This is a very First World Problem, but when I travel to another timezone, Freedom assumes I’m trying to cheat (not unreasonable!) and stays on my home timezone. I wish it would check my actual location (GPS?) and update automatically to match where I actually am.
  • Slack: My most distracting friend groupchat is on slack, and there is no good way (as far as I know) to only block my friend slack while not blocking work slack. I solve that on my primary work computer by simply not logging into friend-slack on that machine, but on other devices I use during the work day (most painfully my iPad) it can be a distraction.

Overall this is an amazing product, and if you struggle with digital distractions I highly recommend it.

Writing elsewhere; the pain of moving platforms

Luis Villa1 Comment

I’ve been doing a lot of writing elsewhere of late. Some links:

  • I’ve written a fair amount in the past year for the Tidelift blog, most recently on the EU’s Cyber Resiliency Act and what it might mean for open source.
  • I wrote last week at opensource.com; the latest in a now multi-year series on board candidates in elections for the Open Source Initiative.
  • I have a newsletter on the intersection of open and machine learning at openml.fyi. It is fun!
  • I’ve moved to the fediverse for most of my social media—I’m social.coop/@luis_in_brief (and you can subscribe to this blog via the fediverse at @lu.is/@admin).

I don’t love (mostly) leaving Twitter; as I’ve said a few times, the exposure to different people there helped make me a better person. But one of my primary political concerns is the rise of fascism in the US, and that absolutely includes Elon and the people who enable him. I can’t quit cold-turkey; unfortunately, too many things I care about (or need to follow for work) haven’t left. But I can at least sleep well.

Book Notes: Summer 2022 (burnout and the good life)

Luis Villa1 Comment

I promised in my post on water to blog more this summer. So far, so fail, but in part it’s because I’ve been reading a lot. Some miscellaneous notes on those books follow.

“An interesting bookshelf photorealistic”, as rendered by Midjourney’s image-creation AI, another summer hobby.

Those of you who have emailed my work address lately will have noticed I’m also on sabbatical this summer, because after five years of focus on Tidelift I’m feeling pretty burnt out. This is not a criticism of Tidelift: it’s a great team; I’m very proud of what we are doing; and I will be going back shortly. But a big theme of the summer has been to think about what I want to do, and how that intersects with Tidelift—so that when I come back I’ll be both a strong contributor, and a happy and healthy contributor.

Work—burnout and better futures

The End of Burnout, by Jonathan Malesic: Malesic puts the blame for burnout squarely on our culture rather than us as individuals, which means the book has very few prescriptions for how we as individuals can deal with burnout. But it has interesting meditations on how we can create a culture that mitigates against burnout.

I hope to do a fuller review soon, because I find it difficult to summarize quickly, and much of it applies to open collaborative communities, where the line between self-affirming creation and self-destructive labor can be very fluid. In the meantime, I’ve put some of my favorite quotes up on Goodreads and annotated many of them.

Imaginable, by Jane McGonigal: I found this equal parts fascinating and frustrating. 

Good: it helped me ask “what the hell am I doing” in much better ways. Two key tricks to this: asking it in a ten year timeframe, and using a bunch of neat futurist-y brainstorming techniques to help think genuinely outside of the box. For this reason I think it might end up being, in ten years, the most influential “self-help” book I ever read.

Bad: it’s a classic “this book should have been an article”, and it is the first time I’ve thought “this book should have been an app”—the structured brainstorming exercises could have been much more impactful if guided with even minimal software. There actually is a companion(?) pay-to-enter community, which so far I’ve really enjoyed—if I stick with it, and find value, I suspect in the future I’ll recommend joining that community rather than reading the book.

Other big failure(?): it focuses a lot on What Is Going On In The World and How You Can Change It, when one of my takeaways from Malesic’s burnout book was to focus less on The World and more on the concrete people and places around me. The book’s techniques are still helpful for this, which is why I think it’ll be impactful for me, but I think it’d be a better book if its examples and analysis also drilled down on the personal.

Place

I’ve had the luxury of spending the summer in Bozeman, visiting my sister and nieces/nephew. So a few books on Montana:

History of Montana in 101 Objects: Terrific. Great selection of objects; thoughtful but concise essays. I wish someone would write the same about SF. Highly recommended for anyone who spends time in the state.

Ties, Rails, and Telegraph Wires, by Dale Martin: A thing that is hard to wrap one’s head around when it comes to Montana is the vastness of the place; fourth biggest state, and 7.5 people per square mile. (CA: 254/mi2; SF: 6,200/mi2, The Mission: 30K/mi2.) This book does a lovely job capturing the vast spaces of Montana at the beginning and end of two massive technological changes: the coming of the train and the coming of cars. Bonus: lavishly photographed (largely via the work of Ron Nixon). 

Water, Climate, and Climate Action

A disconnect I’ve been struggling with is between my digitally-focused work and my increasing concerns for/interest in the Real World. Related reads:

Introduction to Water in California, by David Carle: Recommend strongly if you’re a Californian wanting to geek out, but for most the Wikipedia article is probably sufficient.

How To Blow Up A Pipeline, by Andreas Malm: I recommend every citizen of the developed, carbon-dependent world read this. It might not motivate you to commit violence against carbon-generating property, but it will at least put you in the right place to react appropriately when you see reports of such violence against property. There’s a lot to unpack, and again, I recommend reading it, but at the end of the day much boils down to an image from the end of the book: when the author and other allies took down a fence around a brown-coal power plant, even Green party politicians condemned that as “violence”. The emissions of the power plant themselves? Not condemned; not considered violence in our discourse or politics.

Asceticism I didn’t read

In the past, I’ve on occasion turned to a certain sort of philosophical asceticism when in a frustrated place. So I packed these:

Zen and the Art of Motorcycle Maintenance: I liked this book a lot in my teens and 20s, and much of the focus on Quality still resonates with me. I thought it’d be fun to re-read it in Bozeman (where much of the book takes place). But ultimately I haven’t even cracked the cover, because right now I don’t want to retreat to craft, no matter how well done. Instead, an outgoing, community-centric approach to life feels more appropriate.

Meditations of Marcus Aurelius, translated and annotated by Robin Waterfield: Unlike Zen and…, I have started this one, and would highly recommend it—the translation is very accessible and the annotations are terrific. But again, the detached life feels like the wrong route right now—even if it is one that in the past I’ve fallen into very easily.

Fiction

Read a fair bit of fiction over the summer, much of it light, trite, and not worth recommending or even thinking much about. If you want every detail, it’s in my Goodreads feed; the best of it will get added at some point to my mega-thread of diverse science-fiction/fantasy recs over on Twitter.

Water on the brain; joining OpenET board

Luis Villa1 Comment

I’m becoming a Westerner (in an age of aridification) because I have water permanently on the brain.

An unpaved dirt road, with a large puddle in the middle of it and green grass on both sides.
Sprinkler irrigation, gone awry.
A dark green tree-covered hillside, with a brighter green swathe of grass below it and a browning stretch of grass and a fence in the foreground.
Center-pivot irrigation. Enjoyed showing to A how this looked in satellite.
A farm scene. In the foreground, rows of small vegetables. In the middle ground, a red barn. In the far distance, a snow-covered tall mountain peak.
Drip irrigation, with Mt. Shasta.
Wooded green hills in the distance, framed by a wooden structure. Far off farm accoutrements are visible, including a tractor and farm building.
View from vacation dinner. In almost the center (but you’ll have to squint) was a pump that was filling trucks, moving the water to other (nearby?) farms.
Four forms of water usage, one farm.

Quite related, I’ve joined the board of OpenET to help bring open data on evapotranspiration (a key part of the water cycle) to Colorado River water management, and eventually to the whole world. I’ll be advising on both basics like licensing and of course the more complex bits like economic sustainability, where (via Tidelift) my head mostly is these days.

Many thanks to John Fleck (GNOME documentation project, ret.) for dragging my head into this space years ago by writing about it so well for so long.

Broader opens: on the relevance of cryptolaw for open lawyers

Luis Villa1 Comment

I’ve been thinking a lot of late about what “libre” and “open” mean to me, in large part by thinking about movements adjacent to open source software, and how open software might learn/borrow from its progeny. I hope to go into that more this summer, but in the meantime, I’m publishing this as a related “just blog it and get it out” note.

A chart from a recent presentation I gave on legal topics adjacent to open. Security, DAOs, smart contracts, and Swiss non-profits, among others, show up here and stem from, or are more salient in, the crypto space.

This post started as an email to a private list, giving my best-case argument for why open lawyers should pay attention to crypto/blockchain/web3 even if it’s apparent that most of these things are at best naive and at worst planet-destroying scams. I think it’s worth sharing in public to get more comments and more thoughts on this attempt to steel man the argument for cryptolaw.

So, why should open-adjacent lawyers take crypto seriously?

The Bad Bits

Liability

I’ll start with a point designed to appeal to the most diehard crypto-haters (and to be clear, that’s mostly me too!) Quite simply, crypto (particularly but not just smart contracts) is an almost ideal test case for anyone who wants to bring product liability into software. For decades now, we’ve argued (essentially) that software is too complicated, and so software developers should not be liable when it breaks. And in any case, how do you figure out who owes what to whom when it breaks?

In crypto, those arguments start to look particularly weak. The code is much simpler, and the damages are very specific and clear: “my money(-like-thing) disappeared!” And of course this breakage happens all the time; I haven’t looked but I assume there’s an entire category on Web 3 Is Going Great devoted just to software bugs.

Given all this, lawyers will be tempted to bring product liability cases, and judges will be tempted to resolve them. If that happens, and it finally brings serious product liability to software, what does that mean for our FAVORITE BLOCKS OF ALL-CAPS TEXT? To put it another way: the worse you think blockchain is, probably the more worried you should be about the impact of blockchain on every free software license.

(For this point, I am indebted to Mark Radcliffe, who has been writing and speaking on this issue for a while.)

Ethics, or lack thereof

To continue again with the “the more you hate crypto, the more you should pay attention” theme: lots of developers also hate crypto! In the past year I have been repeatedly asked about anti-crypto riders to attach to open source licenses. This would of course make them non-OSI-approved, but lots of developers hate crypto even more than they like (or are aware of) OSI. I suspect that if ethics-focused licenses ever really take off, anti-crypto energy may be the main driver. How those licenses are defined will make a difference, possibly in clauses that live well-past the current crazy.

The Better(?) Bits

Creates lots of code

To turn towards the more positive side: crypto is one of the most dynamic nearly-completely-FOSS sectors out there; it’d be weird for the open community more broadly to ignore them as FOSS consumers and producers. They write a lot of FOSS-licensed code!

As a practical matter, even if you think tokens/blockchain are likely to fail in the long run, it is likely that some of this code will leak back into non-token applications, so its licensing (and related: licensing hygiene) matters.

Governance innovation

Open source communities have traditionally had at least some members interested in how to govern online communities. Many of us who have been around long enough will have participated in more than one discussion of which version of Ranked Choice Voting to use 😭

Crypto is innovating furiously in the online governance space. As with all “innovation” most of that will turn out to be pointless or actively bad. But as a few practical examples of how it is filtering back into open source:

Again, most of that is somewhere between naivete and scam, but not all of it. Open lawyers (and open leaders more generally) should be aware of these ideas and have responses for them.

Taking ‘freedom’ seriously, sometimes

Related to the previous point, as the Cryptographic Autonomy License process reminded us, at least some crypto communities are taking the principles of free software very seriously and extending them to critical future issues like data governance and privacy. If open source wants to move the ball forward on these values and methodologies, the action is by and large in crypto (even if finding the good-faith action is a little bit like finding a needle in a haystack of greed and scams).

‘Smart’ contracts as new legal form?

Smart contracts are mostly garbage (because they are software and most software is garbage) but the interface of this new legal form with existing institutions is both (1) intellectually interesting and (2) has a lot of parallels to early adoption of open licensing as a legal form/tool. I’d love to interview the author of this paper on smart-contracts-as-vending-machines, for example. Similarly, I suspect there is something to be learned from efforts to bring arbitration to the smart contract space.

Money and interest

Finally, there is, quite simply, a pile of crypto-derived money and therefore employment out there. I personally find taking that money pretty distasteful, but lots of friends are taking it in good faith. Every open and open-adjacent lawyer will be getting questions (and many of will be getting paid for their time) out of that pile of money in coming months and years.

Whether we like it or not, this money — and the people paid by it — will set agendas and influence directions. We need to take it seriously even if we dislike it.

Closing (re-)disclaimer

Again: lots of cryptocurrency/web3 is malicious, and the primary legal response to carbon-emitting proof-of-work should be to figure out how to lock people up for it.

But there are, I suspect, a growing number of overlaps between what “we” do in “open” and what “they” are doing “there”. If we want to be seriously forward-looking, we need to take it seriously even if we hate it.

Editing a background check policy

Luis Villa1 Comment

We’re implementing a background check policy for some roles at Tidelift, because we see security-critical information from our customers. Our background check provider (who I won’t name, because this isn’t about them) has a template policy that is pretty good! But the rest of their product has a very high standard for UX—their designers generally do not settle for pretty good.

https://www.flickr.com/photos/28681973@N00/25648519032
“The red pen bleeds during term paper season… (11/52)” by Rodger_Evans is licensed under CC BY-ND 2.0

Since I know they care, and since employment documents (especially ones that relate to bias) are an important way Tidelift communicate about our company values, I took the time to send them my changes. Having done that work I figured I’d make it a blog post too :) Some notes:

Consistency between software and legal documents

A legal document is, in many cases, a part of a company’s user experience. As such, it needs to be vetted for consistency with the rest of the software, just as you’d vet any other part of the UX.

This is hard, and easy to screw up, because let’s face it—who likes reading and re-reading legal documents? Not even lawyers, if we’re being honest. This particular document screws this up in two ways.

First, the tool (very correctly!) encourages companies not to do a background check for every position, since that introduces a significant bias against people who may have been rehabilitated and should have a fair chance at employment. But the legal document says very plainly that “all offers of employment are contingent on … a background check” (emphasis mine). The legal terms must be brought into alignment with the software’s reality.

Similarly, one of the benefits of this tool is that it takes care of the paperwork for you—without pens and paper. And yet the legal document says that a “signed, written consent will be obtained … in compliance with … law”. Now, good American lawyers know that under the E-SIGN Act of 2000, lots of digital things are “signatures” for the purposes of American law, but most people don’t know that. Good drafting will avoid confusing these non-lawyers by simply saying the consent will be “explicit” and recorded by the service.

Multi-clause sentences and checklists

This is not always the case, but many sentences in legal documents would benefit from being broken up into bullet points, so that each criteria is easier to follow or even treat as a checklist. Consider the difference between:

A decision to withdraw an offer of employment will be made only after conducting an individualized inquiry into whether the information obtained is job-related and a decision to withdraw an offer is consistent with business necessity.  

Original policy

And:

A decision to withdraw an offer of employment will be made only after conducting an individualized inquiry into whether:
– the information obtained through the reference check is relevant to the nature and performance of the role; and
– withdrawal is consistent with the business’s needs.

My revisions

This sounds sort of trivial, but clear writing really can help you spot errors. In this case, breaking up a sentence into bullet points made me notice that the document was inconsistent—an important anti-bias process step was listed in another section, but silently dropped in this list. So someone skimming just the one section of the policy might get it very, very wrong. (Programmers reading this will be nodding along right now—this is debugging by using better formatting to ease code inspection.)

Similarly, where a process is spread across multiple paragraphs, consider using numbered bullet points to emphasize the checklist-like nature of the process and improve the ability to discuss. Much easier to ask “did you do step 4” than “did you do the second clause of the third sentence”.

Q&A style

I continue to believe that many legal documents should at least be edited (not necessarily finalized) in a Q&A style—in other words, changing each section header to a question, and making sure the section actually answers the question. I talked a bit more about that in this post about doing it for a draft of the Mozilla Public License.

In all cases, doing this forces you to make sure that each section has a focused, clear purpose. For example, in the original draft of this policy, there was a section titled “Evaluating Background Check Results”. Revising that into a question (“How will we evaluate the results of the background check?”) helped me realize that one sentence was about a related, but different topic—privacy. Breaking that out into its own privacy section both clarifying the original section and allowed the new section to respond more forcefully to employee concerns about confidentiality.

In the best cases the Q&A framing can really help understanding for non-legal (and even legal) readers. In this case, I found that a well-placed question helped differentiate “why the company does it” from “how the company does it”—which was muddled in the original draft, and important to aid understanding of a tricky anti-bias concept.

Be careful about definitions

Last but not least—you can often tell when a document has suffered from copy/paste when it uses a defined term exactly once, rather than multiple times. Not only does this give you the opportunity to remove the defined term (in this case “Company”) but it also reminds you to give extra focus on the ways that term is used, since it is likely to have copy/paste problems. (In this particular case the stray “Company” thankfully didn’t point to anything worse than jarring word choice—but at least it was easy to eliminate!)

Interested in learning more? Come work with me!

I can’t promise we approach everything with this level of detail; we’re still a small startup and one of the ways we balance the tension between pragmatism and idealism is to Just Get Things Done. But I’m also proud of the way so many of us think through the things some other companies get wrong. If that sounds like fun, we’re hiring!

My teleconf setup

Luis Villa1 Comment

Several friends have asked about my camera/videoconferencing setup, so some notes on that.

Picture from my desktop camera. Lighting isn’t quite as even as I’d like (and as always in stills, my smile is goofy) but you can see the background blur clearly.

Why?

I’ve joked that for lawyers, a good videoconferencing setup is now like a good suit—sort of pointless but nevertheless can help make a good impression in a field where impressions, for better and for worse, matter.

I picked up the new book “Presenting Virtually” from Duarte and it starts with something that’s pretty basic, but also not always obvious—you can’t control networks, and often don’t control what presentation software you’re using. What you do control is your hardware, so make that the best you can.

Camera

I bought a Canon 77D to take baby pictures and… it was in a closet when the pandemic hit. I use it with a 24mm pancake lens. Canon provides a driver that lets you use the camera as a webcam.

Given the cost, I’m not sure this makes sense for most people to do unless they already have a compatible Canon laying around. But if you do have a supported one it works great!

As an alternative, friends speak very highly of this new Dell camera.

Light

I cheat by having good natural light in my office and then supplementing it, rather than having to blast light all over to make up for the gap. This means my light was cheap; the primary criteria was being able to change the color (from a bright white to yellow-ish) so that things looked right.

The exact model I got is no longer available, but is basically similar to this one.

Pro tip for new-ish home workers: if you have two rooms, one dark and one bright, make your bedroom dark and cramped and your office big and light. The previous residents of our place made the reverse choice and I don’t understand it at all.

Microphone

I have a Blue Yeti mic. I’m not sure I’d recommend it for most people. The audio quality is very good, but positioning it over a desk is finicky. (I use these for both my camera and mic, and they work once you get them set up, but they’re a pain.) In addition, it has a headphone jack—which is fine except it insists on reporting to the operating system that it is live even when it has nothing plugged in, so I frequently have to say “no, bad zoom, use the speakers that are actually speakers”.

If I were doing it over again, I’d get something designed more specifically for the home office use case. A friend swears by their Jabra 510, and this new thing from Logitech looks pretty interesting.

What I’m not doing (at least not yet)

I’m sorely tempted to get a teleprompter, but Stephen has mostly convinced me not to. In my experience, at this time, the bar is pretty low—having a good camera and light really does make things noticeably better for people on the other end, even if your eye contact isn’t perfect while doing a slide deck. So you can get a lot of bang for a lot less effort than Stephen spent. Still, tempting some days :)

Hope this is helpful!

Notes on histories: the European nation-state, the Lakota, and Athens

Luis Villa1 Comment

I have been doing a variety of history reading of late, but have not had time to properly synthesize them. They keep coming up in conversation, though, so I wanted to write down some bullet points I could refer to. I hope they are interesting and/or provocative in a good way to someone.

Resemblance to the history of open source was rarely why I read these books. (In fact at least one was read deliberately to get away from open source thinking.) And yet the parallels — around power, mindshare, “territory”, autonomy, empowerment, innovation—keep coming back to me. I leave conclusions, for the most part, for now, to the reader.

Final disclaimer: in the interest of finally publishing a damn thing (I read Ober years ago!), this post will necessarily condense and butcher thousands of pages of scholarship. Please read with that in mind — errors and oversights are almost certainly mine and not the fault of the original authors.

The Sovereign State and Its Competitors, Hendrik Spruyt

Triskelion by Zack McCune, CC BY via Noun Project

This book attempts to understand how Europe got from feudalism to the modern nation-state. It’s explicitly an argument against a view of history where nation-states were inevitable, instead trying to show that there were other possible paths during the late Middle Ages. (The book is very Euro-centric without acknowledging that, which is a shame since I think the book would be well-complemented by an analysis of how European nation-states interacted in colonial settings with non-nation-states, about which more later.)

The core argument goes something like this:

  • what is feudalism anyway? at some level, it means “no entity has a monopoly on power in a territory”, because feudal lords, the church, tribal-like kinship relationships, etc., all overlap and interact in complicated ways.
  • you get out of feudalism, and into nation-states by:
  • punctuated-equilibrium-style evolution: a major shock to existing system (in Spruyt’s analysis, massive economic growth starting in c. 1000) which creates new power centers (bourgeoisie and new cities), which destabilizes feudalism and …
  • creates a diverse set of post-feudal options: wealthy, powerful city-states in Italy; leagues of cities in Germany; something like the modern nation-state in France. (It is this diversity which Spruyt says a lot of historians ignore, and certainly which American high-school history completely ignores.) But…
  • that situation (with a lot of different, competing options) is unstable even if each individual solution makes sense for that place/time (i.e., “city-states were stable in/good for Italy” and “city-states were not stable in/fit for Europe” can both be very true), so then…
  • competition and conscious self-selection leaves you with modern nation-states on top, for a variety of reasons, including simply that nation states prefer negotiating with other nation-states; i.e., hard for France to make treaties with a loose coalition (league) of cities, so it partners with (and therefore empowers) other units like it.

I would love to see a similar analysis for the history of various corporate forms or industries. I’ve seen it suggested, for example, that the combination of the telegraph and the railroad made multi-jurisdiction limited-liability corporations the dominant form in the US, but there was nearly simultaneously a huge explosion in experimentation around cooperatives—should we complicate the “telegraphs → big companies” narrative in the same way Spruyt is attempting to complicate it here for the transition from feudal society to nation-states?

The mapping to open source is probably pretty obvious: internet-enabled development (and then internet-enabled distribution) delivered a shock to the existing software business ecosystem; for a time we had a flourishing of institutional/organizational forms. There is certainly a narrative (perhaps correct? perhaps not?) that we are settling into a new equilibrium with a smaller number of forms. What might this history tell us about where we’re going (and what questions we should ask about the narrative of where we’re going?)

Lakota America: A New History of Indigenous Power, Pekka Hämäläinen

Las Labradas by Zack McCune, CC BY via the Noun Project

US history books rarely show Native American tribes as entities with agency—the world acts on them, but not vice-versa. This book aims to be an antidote to that, showing over a course of roughly 200 years how the Lakota acted, learned, and changed in response to the world around them (including, but definitely not limited to, the US).

I definitely did not read this with the intent of “oh, this will make me think about open source”; I figured it was about as far away as I could get, and yet as I read I couldn’t help but think about parallels.

I think it’s important to be clear: by drawing parallels here I definitely don’t want to suggest that changes in open source are in any way morally/ethically comparable to genocide; if (free?)/open source culture vanished altogether tomorrow that would be a genuine tragedy, but an extremely minor tragedy compared to the very deliberate genocide that occurred occurred in North America.

But it’s hard not to see parallels in the gradual encirclement and disruption of one culture by another very different culture. Some other thoughts:

  • In one of the many ways in which the book thoughtfully gives the Lakota agency, the author writes of that “[t]hey had welcomed America’s merchandize but not its paternal embrace; they had accepted the Americans as traders and potential allies, but not as their sovereigns. They had, in other words, refused to be ‘discovered’ by [Lewis and Clark]”.
  • Just like in Spruyt’s Sovereign State, much is made of the simply different notions of “territory” between the nation-state and its competitors; in this case, between the Lakota whose governing style the book describes as “ranging widely but ruling lightly… a malleable, forever transmuting regime”, with little attention to borders or even ultimately to control, and the Americans who “were content with a cartographic proof of.. sovereignty”, needing (and imputing power to) lines on a map.
  • Technology is a small but significant undercurrent in the book: first guns, then horses, then ultimately the railroad. The first of these two were enthusiastically adopted by the Lakota, and indeed powered much of their imperial expansion in the 1800s. But they could not adopt the railroad in the same way. Nor was writing, though he does say that “[a] key element of Lakotas’ diplomatic prowess was the fact that they had so many literate allies who interpreted and explained [American] documents for them.”
  • “Contemporary Americans saw the Powder River country as an Indigenous retreat, an insular world intentionally cut off from the rapidly expanding American empire of cities, railroads, settlers, farms, ranches, and capitalism—a perception that has dominated outsider views of the Lakotas ever since. In reality, the Powder River country under the Lakota rule was a safe and dynamic cosmopolitan world of its own where transnational commercial circuits converged, where Indians enjoyed many comforts and advantages of the industrial age, and where new ideas about being in the world were constantly debated. Lakotas knew full well that they lived in a transitional period of innovation, quickening change, and questioning of old conventions. But contrary to the tired old stereotype of obstinate, tradition-bound Indians, they embraced this radical regeneration of their world.”

Additional selected Kindle highlights from my read are here.

Democracy and Knowledge: Innovation and Learning in Classical Athens, Josiah Ober

Moab Owl by Zack McCune, CC BY via the Noun Project

Ober is a data-driven classicist, focused on Athens and how it fit into the broader milieu of classical Greece. In my distant recollection, this book (or perhaps often just my takeaway from it) argues that:

  • Since you have literally a thousand Greek city states, you’re running a real experiment you can draw real conclusions from. And Athens, in a real material sense (backed by a variety of interesting data sets) “won” this experiment. (This has some parallels to Spruyt, arguing that in essence there was a flourishing of alternatives and then a winnowing.)
  • This greatness was in large part predicated on Athen’s ability as a democracy (relative to its neighbors, at any rate) to create and synthesize effective knowledge. In other words, it was better at being a government specifically because it was a democracy, using “local”/small-group/individual knowledge to make itself more effective.
  • Athens then ultimately failed (after nearly 200 years) in part because neighboring oligarchic governments took its good ideas, and re-implemented them. (This issue is also explored in Ober’s Rise and Fall of Classical Greece.)

I do wish I still had my original notes from reading this a decade or so ago; both it and Rise and Fall are deep and rich books that stirred my political theory bones in a great way.