
I recently finished reading _Working in Public: The Making and Maintenance of Open Source Software_ by [Nadia Eghbal](https://nadiaeghbal.com/), thanks to a book club organized by [Chris Traganos](https://twitter.com/chris_trag) at [Stripe](https://press.stripe.com/). While I can't say this is a book I would have found my way to own my own, I found myself tearing through it far more quickly than I would have guessed. I'd fully recommend giving it a read - you can pick it up on [Amazon](https://smile.amazon.com/Working-Public-Making-Maintenance-Software/dp/0578675862).

Below is a pretty raw copy/paste of my notes on _Working in Public_, which I take in Roam Research as I read. If you'd like to discuss any of this with me, drop me a line on [twitter @irreverentmike](https://twitter.com/irreverentmike).

**Notes on _Working in Public_**

# Part 1

## Chapter 2: The Structure of an Open Source Project

- &#8203;
  <Highlight>
    Developers don't contribute to open source for lack of technical ability,
    but rather due to fear of committing a faux pas
  </Highlight>
  - There's a huge hurdle to get over here, particularly for new contributors. Even
  sending a very small PR or opening an issue has a mental tax associated with it
  that can prevent progress, community from being built
- &#8203;

  <Highlight>
    The process of getting a change approved depends, among other things, on the
    **complexity** of the change (and the complexity of the project), as well as
    one's **reputation** among those with the ability to approve the change.
  </Highlight>

  - Reputation is a tricky currency, particularly when some folks build clout by
    being funny / sarcastic to gain viral notoriety. This doesn't necessarily equate
    to value to the community or trustworthiness, but often can be parlayed into exactly
    that.

- &#8203;

  <Highlight>
    If a project's contributor base is growing rapidly, and there is enough work
    to hand off, maintainers may start to distribute work more widely. In a
    **distributed** state, maintainers actively recruit more contributors to
    pitch in, with the goal of retaining them in the project.
  </Highlight>

  - At some point, the success of a project causes a requirement for a shift in operations
  - from building the thing to **supporting** it, and recruiting community members
    to help get things done on either end of that. Teams' ability to make that pivot
    is critical to success.

- &#8203;

  <Highlight>Healthy open source (re: node.js contribution policy)</Highlight>

  - Design a contribution policy and code of conduct which entices contributors **and** retains them. Based on my experience, this is the magic in getting something over the hump from being fledgling to more broadly successful.

## Chapter 3: Roles, incentives, and relationships

- Open source developers were frequently characterized as "hobby" devlopers
  - Hm! TIL.
- A theory of the commons
  - In the last half of the 1900s, economist Elinor Ostrom came up with an 8-part theory to what makes up a successful "Commons", or resource that is owned, used, and managed by a community. These rules outline the basic tenets of what makes a successful commons, and apply directly to successful OSS in many ways.
  - Making sure members are biased toward **working together** is a key to success. This may mean distributing knowledge and capability so that everyone has value and meaning, and no one person can hold up the process. Obviously encouraging collaboration is a valuable outcome here, too - so empowering folks to use each other as a resource is extremely helpful.
- <Highlight>
    Intrinsic motivation makes it easier for people to self-organize to achieve
    the same outcome.
  </Highlight>

- The newcomer effect
  - <Highlight>
      "Because newcomers have not yet developed commitment to the group and have
      not yet learned how the group operates, it is rational for established
      group members to distrust them"
    </Highlight>
  - This happens all the time in OSS - many projects have core maintainers who
    do all the work, and a significant amount of gatekeeping by way of bluntly shutting
    down PRs or issues when they're disinterested in them. It's fair to say that
    for the contributors getting shut down, a steady and consistent participation
    in the project will help them get notice, but it can feel like an unfair hurdle,
    too. What might be a more equitable solution to this? Not empowering code owners
    as much? Adding an objective, third party moderator to make some decisions?
- All Contributors
  - https://allcontributors.org/
  - Recognize All Contributors Including those that don't push code
- On Contributors...
  - Again, I'm reminded of the madness of Hacktoberfest 2020 - lots of garbage contributions from people just trying to get a free t-shirt does not make for good OSS, good community, or good contributions.
  - &#8203;<Highlight>Bus Factor</Highlight> is the number of contributors in a project
    who would need to be hit by a bus for it to be in jeopardy. lol

# Part 2: How People Maintain

## Chapter 4: The Work Required by Software

- Software, once written is never really finished. Chasing the feeling of a "finished" app/program/site is something that took me FOREVER to get over. I never felt like I had done anything, because nothing ever got to the finish line. It turns out that the finish line doesn't exist, and a decade+ of building "incomplete" things was the catalyst that I needed to figure that out. As such, <Highlight>greenfield</Highlight> projects are "coveted" because they're a blank canvas, enabling us to chase that feeling of a fresh _starting line_ to point us to a goal that is always just past the horizon. It's a feeling of hope - and thankfully a beneficial one, as rebuilding software from scratch is often inherently beneficial. Neat.
- <Highlight>Free as in speech, not as in beer</Highlight> vs <Highlight>
    free as in puppy
  </Highlight> is a brilliant analogy
- <Highlight>
    By focusing too much on iterating upon their incumbent product, companies
    risk missing major opportunities for so-called "disruptive innovation,"
    which eventually replaces existing products. - Clayton Christensen in Book:
    The Innovator's Dilemma
  </Highlight>

- The anecdote about Sophie Alpert being offered $600 to **open a PR on someone's project** because it would draw positive attention is mind-blowing.
  - "Is this what it feels like to be an influencer?" - Sophie
- <Highlight>
    We can think of a creator's reputation as a "battery," or store of value,
    for attention. More followers mean more attention in the bank, but when
    people follow a creator they do so because they expect to receive more
    content. If creators don't produce anything new, their followers will
    eventually get bored and leave. Reputation, like software, requires
    maintenance over time.
  </Highlight>

## Chapter 5: Managing the Costs of Production

- Absolutely mind-blowing that at one point, cryptographic code was treated the same as munitions by the US government. Early developers of OpenSSL <Highlight>had to become licensed arms dealers to be able to write and "export" (i.e., distribute) their code.</Highlight>
  - This is an implicit declaration that certain types of technical solutions can be weaponized, and perhaps just as importantly that sometime in the past, some of our legislators had a reasonable understanding of this. In the US, at least, it's apparent that this is no longer the case. Don't believe me? Pull up a congressional hearing with Tim Cook, Zuckerberg, etc
  - Relatedly, it is asymptotically difficult for lawmakers to keep up with the changing pace of technology. There's a decent argument to be made for a citizen-run, or commons-run governing body for technical regulation, rather that trusting some crusty old white men from flyover states whose pre-government professional lives weren't the least bit technical.
- <Highlight>
    When software is in static state, **what if there is no free-rider
    problem?** When code is non-rivalrous, it only has first-copy costs, which
    the creator is intrinsically motivated to provide -- so the problem doesn't
    seem to lie in how many people **consume** it. For this reason, I'm
    skeptical of attempts to charge for access to information, whether it's
    newspaper articles or open source software.
  </Highlight>

- This hints at one of the most fascinating things about content creators online. Virtually all of the really, truly successful creators are driven by an enjoyment of creating and sharing -- and might not typically start creating as a business. Often times it takes hundreds of youtube videos, or dozens of podcast episodes, blog posts, etc to get any kind of sizeable following. It's those with the fortitude and perseverance to continue without an audience that find success. Perhaps the audience is their reward, or perhaps the audience is a natural byproduct of the law of large numbers: create enough of something, and put it out into the world, and **some size** of audience will find you.
- <Highlight>
    At a high level, it's also possible that throwing away projects and starting
    fresh is the most cos-effective approach: rebuilding the whole system, piece
    by piece.
  </Highlight>

- There are many companies that operate like this - occasionally dropping an existing product for a **completely new** rewrite. This has been done with projects as small as weather apps and as large as Windows and MacOS, and is often a good decision. It strikes me that this is often only possible due to a luxury of funding, time, and resources. Imagine telling a scrappy startup that their best bet is to ditch their entire source library, and start anew. It wouldn't work! Many fledgling companies fall apart because of early and inflexible assumptions made, or technical debt built up to save time. The luckiest of them find success despite this debt, and carry on to be successful. I'd imagine this success often brings about an effort to rebuild the plane while it's flying, in a modern Ship of Theseus paradox.
- Automation! This section rang true with me to the core. When building [smpl](https://www.crunchbase.com/organization/smpl-llc), our biggest superpower was automation. It made our engineering team of 2 feel much larger than it was, and helped us to execute successfully and dependably. To this day I think that process automation is the closest thing I have to a superpower.
- It's interesting that a book about OSS has me thinking about work, content, and contributions outside of software so often. So much of what's discussed here has interesting implications politically, socially, and in content creation of any sort for public consumption (art, blogs, youtube, instagram, etc)
- I didn't know about [dear-github](https://github.com/dear-github/dear-github) or its relatives [dear-github2](https://github.com/drop-ice/dear-github-2.0) and [isaacs/github](https://github.com/isaacs/github). It'll be interesting to give these a read. As of this writing, `dear-github2` has had activity as recently as 2 weeks ago

### The role of Money in OSS

- Companies pay for access, attention, and feature proposals. This can often have adverse effects: companies are essentially skipping the line to pay for attention, and as a result aren't vetted by the same processes as other OSS Contributors (particularly those who request fixes and features). This can be a governance nightmare, and can cause mistrust in a project if done incorrectly.
- Advertising in OSS projects has real untapped potential, but often gets shot down. There was a product called Code Fund by Eric Berry which aimed to put ads into the readmes of OSS repos on github. It rose to $24k/mo revenue in 4 months before GitHub shut it down as a violation of their ToS.
- Trivago appears as a sponsor on Webpack, and this has helped them to recruit JavaScript developers, who see them as a good company to work for as a result of their support.
- An interesting difference in funding projects comes by way of GitHub's sponsors feature (and other services like Pateron), whose goals are more oriented towards having individuals back a **contributor** (rather than a project) on a monthly basis. The subscription is seen as a vote of confidence in the person, rather than slippery backing for a single project.


Book notes: Working In Public


**Note:** This post came from my work on [Surviving Other People's APIs](https://leanpub.com/surviving-other-peoples-web-apis). I've been working on a chapter on **Async** - the content below came from that writing, but doesn't quite make sense in the context of the book. I didn't want to scrap it entirely, so it's found its way into a blog post. I'd love to know what you think!

## Plan for things to go wrong

Setting up an interface to pull data from an API asynchronously is a clear upgrade over the alternative; we're now able to update the content on a given page without reloading all of the markup and assets (images, css, etc) on the page. For better or worse, your asynchronous upgrades will also introduce some potential for things to go wrong for the people using your app. Once again, this is an opportunity to anticipate the things which might go wrong, and build fallbacks for when they do.

### Dealing with dropped connectivity

Even if you've used a hyper-modern, robust websocket-enabled API-calling technology, at some point or another, the folks using your app will lose their internet connectivity. This isn't just the canonical example of someone on a train going through a tunnel, either. Often times connectivity will go down briefly for mobile users when they switch from a cellular connection to wifi, or when they go between wifi networks, or when they lose wifi and go back to cellular.

You should test your software to make sure it will continue to work in these cases. It turns out this can be pretty easy to simulate, too - if you're on a phone, turn airplane mode on, wait a moment, and then switch it off again. On a laptop or desktop developer environment, you can switch wifi off, or disable your LAN connection. Even better, if you're using Chrome devtools, you can use their responsive tools to shut off connectivity on a single tab:

<Image
  publicId="posts/plan-for-things-to-go-wrong-in-your-web-app/chrome-devtools"
  alt="Screenshot of the throttling interface in Chrome Devtools' responsive mode"
  caption="Chrome DevTools has a simple switch to shut off connectivity"
/>

Once you're able to simulate this kind of trouble, you can build out fallbacks for when things go wrong. A typical approach to this is to keep track of the result of your API call locally. If a drop in connectivity is detected, you should let the user know that it looks like they're offline. From there, you can give them the opportunity to retry the API call, and automatically retry your call when you can tell things are working correctly again.

<Image
  publicId="posts/plan-for-things-to-go-wrong-in-your-web-app/recover-from-offline"
  alt="Mockup of a mobile app showing a modal popup notification for when internet connectivity goes down, which takes over the entire screen."
  caption="Recovering from a dropped connection during an async save operation"
/>

Certain technologies will do the bulk of this work for you. For example, if a connectivity drop is detected, Firebase will save any API operations to a queue in the client browser's local storage, and will execute offline changes as soon as connectivity comes back. Even still, as when creating interfaces which take advantage of features like this, you should let your users know when they're offline. It's best to fully communicate what will happen when the connection comes back, too - in clear, human-friendly language.

<Image
  publicId="posts/plan-for-things-to-go-wrong-in-your-web-app/working-offline"
  alt="Mockup of a mobile app which informs the user they're working offline, and that changes will be sync'd when the connection comes back."
  caption="Explain clearly what will happen when the connection comes back"
/>

Note that in this case, we have the opportunity to create an interface which is a whole lot less shouty than in the last example. There's no need for the offline notice to be put in a modal window which takes up the whole screen. Colors are dialed back a bit, too - yellow is used in the example, which is much less anxiety-inducing than the-sky-is-falling-red.

As a follow-up to this, when the connection comes back, it's good practice to fire off a notification when the offline requests are completed successfully.

### Dealing with changing APIs

At some point, the APIs you're calling will change. In an ideal world, these sorts of changes are well-documented, and deprecation notices are made available months in advance of permanent changes which will break your application. It is part of your team's job to keep an eye on any services you use for breaking changes coming your way. This can be as simple as assigning a task every sprint to check for API and dependency updates.

This is a perfectly functional approach to watching out for version changes -- until it isn't. For larger applications, you may find that as you build more features which depend on a growing number of external services and dependencies, this task becomes an untenable time sink. Luckily, in many cases, there are ways to automate the process. One such tool is called Dependabot, which is owned by the folks at GitHub.

<Image
  publicId="posts/plan-for-things-to-go-wrong-in-your-web-app/dependabot"
  alt="Screenshot from dependabot's marketing page"
  caption="Dependabot can be found at https://dependabot.com"
/>

Dependabot (and services like it) will keep an eye on dependency lists in your project (like `package.json` in Node projects, and `Gemfile` in Ruby projects). Once initialized, it will regularly check your dependency lists against the published versions of each library. When new versions are published, it'll open a simple pull request for each updated library, which you can review, test, and merge when ready.

<Image
  publicId="posts/plan-for-things-to-go-wrong-in-your-web-app/github-dependabot"
  alt="Screenshot from github.com showing a repo with automated Pull Requests, created by dependabot"
  caption="Lots of small pull requests - one for each library which has been updated!"
/>

Generally speaking, this makes the task of keeping dependencies up to date much simpler. The majority of the work can now be done by your test suites via CI - and changes can be verified by reading changelogs for each updated package.

As this becomes more common, maintainers of various libraries are getting better at posting easy-to-understand changelogs, which reduces the chances that you'll merge a catastrophic change into your project. These kinds of proactive measures should help you sleep more soundly at night.

Even still, sometimes things go wrong for one reason or another.

Maybe you merged and released a dependency update which has a breaking change to a mission critical API. Maybe one of your web page uses an API with a version set to `@latest` (!), and you wake up one day to find hundreds of help tickets from people who used to love your application. If you had been keeping an eye on server logs for your application, you may have noticed that overnight you received a spike in 4xx or 5xx errors from API calls. Be honest with yourself - how often do you proactively check server logs for errors? Don't fault yourself if the answer is less than often - most of us never check.

Once again, this is a place where automation can save the day. There is no shortage of tooling available to help you detect problems reactively just as they start, and with a nimble enough release strategy, you can minimize application downtime.

### Use error reporting to turn reactive situations into proactive messaging

Imagine this: you're in charge of an application which uses an external service to check the weather for [whatever purpose]. You've got thousands of happy users who regularly use your app to check the weather before going about their day. One day, without warning, the weather API begins sending back data in a completely different format than you'd expect - a change big enough to render your app useless.

In the old world, you wouldn't find out about this problem until help tickets and angry tweets started rolling in. At that point, it's past too-late - your beloved customers are upset, and you're the fireman who showed up after the roof collapses on your house.

We can do better than that.

There are a plethora of services available which will detect and report application crashes to you the instant they happen, so your support team can spring into action at a moment's notice. Some of these services include [Raygun](https://raygun.com/platform/crash-reporting), [Sentry](https://sentry.io/), [LogRocket](https://logrocket.com/), [Rollbar](https://rollbar.com/), and [Data Dog](https://www.datadoghq.com/). With a few lines of code, these will plug into your app, and keep an eye on network requests. When a page crashes, they'll fire off all manner of notifications - SMS, email, webhooks, Slack messages, you name it.

If you can't afford to use one of these services, or otherwise prefer not to, you can scrap together a simple one yourself. This generally looks like a wrapper function which you can use to call APIs. It should contain the logic to detect failures, and fire off whatever calls are necessary to alert your team to the problem. For teams with a small budget, the easiest approach may be using Slack's incoming webhooks feature to send a message to a channel dedicated to an application crash:

```javascript
const callApi = async ({ url, options }) => {
  try {
    // send off the API call
    const response = fetch(url, options);
    return response;
  } catch (e) {
    //something went wrong, let's notify the team!

    /* helper function to gather as much information as possible about this session, possibly including:
      - user name and contact information
      - URL or page they were visiting
      - which action caused this error
      - browser metadata ("IE7" or "Firefox 58", etc)
      - anything else that might help your support team send a thoughtful, personal response!
    */
    const metadata = getUserMetadata();

    // just what it sounds like - send a message to your team's slack channel via incoming webhook
    sendSlackWebhook({
      error: e,
      metadata: metadata,
    });

    // send the response back to the interface so you can let the user know something went wrong
    return e;
  }
};
```

These can greatly decrease your effective response time. If you're able to detect these problems and set your dev team off on a solution before users start complaining, the people using your app will feel loved. Think about how rare it is to use software and feel like the people who are making it care about you directly! If you're a small, scrappy start-up, this can really help you hang on to early customers. If you're a larger company, it means lower attrition rates, and better support ratings.

Error reporting can also help you detect crashes with user-by-user granularity. You may see crash reports coming in from a single user over and over. Reaching out to that individual to see how you can help them before they message you can honestly feel like magic. I've even had users thank me for dropping them a line and telling them I see that they're having trouble, and that I'm on the case. It's a great feeling - particularly when the alternative is a red-hot support email or a scathing tweet.

### Build a global status indicator... before you need it!

In all of the projects I work on, it's become common practice to include a global status indicator into the fundamental roots of the application. In its simplest form, this amounts to a content container that lives somewhere near the very top of every page off the application. The vast majority of the time, it sits invisible and dormant. On page load, and once every few minutes it checks our CMS for content - if something goes wrong, we use that field in our CMS to alert users to the issue, and update it regularly with easily understandable messages about resolution of the issue.

If you don't use a CMS, never fear - you can use something like GitHub Pages to host a json file which you can use for these kinds of warnings. Have your interface check the public URL of your GitHub Pages site, and if there's anything more than a blank file or object, that content can be parsed and displayed in your status indicator.

### And then?

For now, that's it! Like I mentioned, this was just an excerpt from a chapter that didn't quite fit with what I'm writing. What do you think? Is there anything you do to harden your site against failures that are out of your control?


#book: 2 posts tagged

Book notes: Working In Public

Help your users when your web app crashes

.css-1fb0br2{color:#A0AEC0;}#book: 2 posts tagged

#book: 2 posts tagged