A journey to building better blocks

The Travelers, by Henry Macbeth Raeburn

Nobody – at least nobody we know – lives in a vacuum. Except probably dust mites.

In the Open Source world this is especially obvious: whenever we add a line of code, or comment on an issue or pull request, whether we’re aware of it or not, we’re entangling ourselves with a vast network of developers, designers, users and contributors, all of whom, despite having diverse experiences and opinions, share a common goal: to build a better web.

On our way to “Building Better Blocks” for the Gutenberg editor and the WordPress project this goal remains in our minds, propelled by the exciting knowledge that, with the right balance of discovery, compromise, collaboration and experimentation, anything is possible.

As with any journey, there are challenges: ideas turn stale, work stalls, we find ourselves staring at walls wondering where to go next.

Yet along the way, we’ve learned a few things that have made our adventure more rewarding and amusing. They’re applicable to any large Open Source project I think, but we’ve drawn them specifically from our experiences working on Gutenberg.

We hope they’ll help you too.

Work that goes nowhere can lead us somewhere

Time and effort devoted to developing a feature or solution to a problem that never makes into the final product is not wasted if we learn something. 

For example, we might have implemented a prototype for a design, spent days crafting, writing tests, honing the user experience, and seeking feedback but learn only after that the approach is flawed in some way.

We’ll use that information to guide the design in a new direction. File it under “research”. It’s all good.

We find it’s also useful to write a summary of why we’re closing a pull request and link to follow ups, if any.

Even if it’s not us, one day, someone will come along and pick up the thread where we left off and build upon our knowledge.

Leave sign posts

Discussions can grow very large. They might change the direction of a PR multiple times. They may even appear to go in circles. In fact, sometimes they do.

This is also all fine. It’s just humans working things out.

Where a loop has been closed, or a pull request takes a new direction, we’ll close that PR and create a new one.

When doing so, it’s very helpful to add backlinks to the original pull request in order to reduce research time for reviewers and contributors both new and experienced.

You have more fellow travellers than you think

Knowledge varies wildly between individual Gutenberg contributors, so include prior history, discussion and context in PR and Issue descriptions, or at the very least, links to where folks can find all that.

This is not only helpful to new contributors, but to other folks such as reviewers, release leads and product managers, all of whom need to be able to gain a quick overview and understanding of the code, how it fits into any milestones, and the reasons behind changes.

You might have an intended audience in mind, yet you can’t know in advance who’ll land on your pull request or issue via backtracking, via the WordPress Core blog, or otherwise. It might even be your future self returning after a long, and probably well-deserved break.

Investing a few extra minutes describing the what, how and why behind your pull request in the description field, in addition to how to test your changes, what to look for in a bug fix or bug report, will help others to understand your proposal/changes. So too will creating informative screenshots or demos. We will love you for it.

Don’t be afraid

There are high standards, yes. We’re sharing this journey with clever and experienced (and stylish!) people, whose opinions will influence the course of our work.

Remind yourself: you can afford to be brave. You can experiment with ideas, defend them in the discussions. 

Collaboration brings with it many opinions, and (theoretically) fewer top-down imperatives: you have the opportunity therefore to learn and contribute to conversations on a relatively level field. 

Convince us by code or design demos or rhetoric. Strive for compromise and excellent outcomes for users.

Take time to smell the coconuts

Open Source runs on its own version of “island time”, which is not to say that nothing happens, more so that things happen when they need to.

Discussions on issues or open pull requests may appear to never progress, or will be dispersed across many media and be asynchronous. Pull requests sometimes hit a roadblock or ten roadblocks as new dependencies and use cases arise.

The process of discovery and collaboration is, even if we don’t notice, always evolving.

It can be frustrating to have your work interrupted or placed on pause. Use the time to read deeply and build context. We’ll all get there.

In the end, the journey is as important as the goal.

Leave a Reply

Your email address will not be published. Required fields are marked *