Image: Mozilla

The Rust community isn’t unique in crafting vision docs that help to ground contributors in a common vision for the future. What is perhaps unique is that the Rust community also includes narratives that detail the status quo for the project. It’s important to have a community working together toward a common future; it’s imperative that everyone understand the delta between “here” and “there.”

Rust does this with vision docs and status quo narratives that walk through “the challenges encountered by one of our [Rust users] as they try (and typically fail in dramatic fashion) to achieve their goals.” Here’s how they work.

SEE: Rust: What developers need to know about this programming language (free PDF) (TechRepublic)

Where we want to get to

Niko Matsakis leads the open source Rust language design team. For years, the Rust community has relied on a Request for Comments (RFC) process to guide development. But RFCs are just part of a larger process designed to coalesce the community around a common vision, as Matsakis has written:

If you look at a description of the design process for a new Rust feature, it usually starts with “write an RFC”. After all, before we start work on something, we begin with an RFC that both motivates and details the idea. We then proceed to implementation and stabilization.

But the RFC process isn’t really the beginning. The process really begins with identifying some sort of problem – something that doesn’t work, or which doesn’t work as well as it could. The next step is imagining what you would like it to be like, and then thinking about how you could make that future into reality….

The role of a vision doc is to take that implicit framing and make it explicit. Vision docs capture both the problem and the end-state that we hope to reach, and they describe the first steps we plan to take towards that end-state.

Vision docs are still in gestation within the Rust community. They’re used, but not universally. Their utility will hopefully make them standard operating procedure within Rust and other communities, because they help to provide context and guidance to RFCs or other mechanisms projects use to frame their common objectives. It’s easier, for example, to know the utility of a pull request if a maintainer can compare what it hopes to accomplish with the vision of the project.

Vision docs promise to help Rust (and other communities), and not solely because they define a desired end state that all contributors can build toward. There’s another element, easily overlooked, that might be even more important than articulating that vision of where to go.

And that is to clearly identify where we are. Today. Now.

Where we are

Most open source projects will outline technical hurdles to be overcome–what they don’t do is to situate these hurdles within human context. By writing these out, identifying where a common user of a project may get tripped up, maintainers are able to see beyond themselves. Or, as Matsakis stressed, “Writing the ‘status quo’ stories helps us to compensate for the curse of knowledge: the folks working on Async Rust tend to be experts in Async Rust.” As an expert in a given project, you’re all-to-familiar with the workarounds that a newbie won’t know. You work around these blind spots; they trip over them.

Not that it’s easy to use the status quo narratives successfully, as Matsakis noted: “When we started writing ‘status quo’ stories, it was really hard to focus on the ‘status quo.’ It’s really tempting to jump straight to ideas for how to fix things. It took discipline to force ourselves to just focus on describing and understanding the current state.”

SEE: Top 5 programming languages for systems admins to learn (free PDF) (TechRepublic)

Doing so, however, helps to ground the project in the real-world (and real-people) problems the project hopes to overcome to reach its vision. “In working on Rust, we’ve always found that focusing on accessibility and the needs of new users is a great way to identify things that–once fixed–wind up helping everyone,” said Matsakis. This is particularly true of those errors likely to trip up newcomers to a project. By writing “stories” about them, a project can anticipate their challenges and work to overcome them.

It’s an interesting idea, and one that seems to be working for Rust. Maybe it will work for you, too.

Disclosure: I work for AWS, but the views expressed herein are mine.