A tale of a typo – can we talk about making things easier for contributors?
Monday, December 9th, 2019 at 4:52 pm
The other day someone asked me to help them with a project and take a look at a single web document. Nothing fancy, one document with a bit of text and some design. No interaction, no special ”app” needs. I looked at the page and I found a typo. Normally I’d write a report of what could be done better. But I thought I’d be a good web citizen and go to GitHub, fork the project and do the changes myself adding comments why I did so. I also thought it a sensible thing to run the project locally to see the changes.
As it turns out, the project used not markdown or HTML, but a templating engine. Building the project locally meant downloading 150 MB of dependencies. It then failed because I tried it in my Linux shell on my Windows machine. Some of the dependencies flat out expected a Mac without any information about that.
In the end, I fixed the typos directly on GitHub using the raw view. I encountered some waste of time and effort and I am OK with that. However, now imagine me being a person that just wants to help out an open source project. A non-affluent person on low-level hardware on an unreliable or expensive connection on the web. Not using the web interface of GitHub would mean I am blocked and I paid the price of downloading 150MB for it.
We should be better than this. There are lots of articles on how to make our products perform well for end users. But what about the technical, cognitive and monetary efforts we expect from contributors? Shouldn’t it be easy for anyone to participate rather than just those with the fastest computers and the best connections?
Nobody thrives in complex and demanding environments.
Most of our work on the web these days demands us to have a local server or local workflow running. In the past, this was a sensible thing to do. I can’t remember a time when I didn’t have an Apache, Tomcat, Resin or PWS/IIS running on device as being online wasn’t the norm.
It is still sensible to have a local setup running of your product. It becomes less so when we spend most of our time downloading, configuring and fixing that setup. We deal with an increased complexity of our toolchain. And that can block out a lot of potential contributors, learners and beginners when their first experience mirrors mine.
What’s the alternative?
What I did made a lot of sense to me. Editing in the browser, still writing good comments and sending a pull request. We’ve always belittled online editors as last resort solutions. Things changed though. These days they do not only give us a good editing experience . They can also prevent people from installation and configuration frustrations. If I want to play with TypeScript as a language, why should I first have to set it up?
It is exciting to see how CodePen, Stackblitz, Codesandbox, JSBin and others empower developers day to to day to become creative and try things out without overhead. Development environments built into browsers become more capable each day and even high end IDEs like Visual Studio now consider an online version.
People like Ana Tudor work exclusively in online editors and her work is stunning. All she needs to get started is a laptop and an internet connection. And there are even extensions and tools to allow her to write offline in the editors she is used to.
I love how far the web has come and I think collaboration is the only way software can survive in the long term. We should make it as easy as possible for people to contribute. And that does not mean for them to fragment their computer with lots of complex project setups and configuration.
There’s lots of documentation and coverage of how to make our final products perform well for our users. Maybe it is also a good time to stop, look around and consider the performance of developer environments. And the overhead we demand from potential contributors.