How Microsoft uses walkthroughs to guide open source development

Microsoft’s shift to open development models is an interesting case study in how to manage open source development at scale. With millions of users and thousands of potential contributors, the company’s project maintainers have problems that most open source projects haven’t yet had to face.

At Microsoft’s level of scale, a project maintainer is more akin to a product manager or project manager than a development lead. They’re working with both internal and external contributors, while trying to direct effort into delivering on items in the project backlog as well as fixing bugs and issues. Then there’s the task of managing feature requests, in many cases working with volunteers new to the project and to the constraints of delivering enterprise applications.

Collaboration at scale in GitHub

While codebases may well be visible in GitHub, the availability of source code is no substitute for collaboration. How does a new contributor find their way to the right section of code to make necessary changes? Searching through a cloned repository and adding breakpoints while running a debugger is one way of working, but it’s tediously dependent on trial and error. Volunteer time is a valuable commodity you don’t want to waste. It’s also far too easy to lose, with attention drifting off to friendlier projects.

That’s led the Windows open source team to start experimenting with a new process in one of its more popular codebases, Windows Terminal. Where work is needed, the project maintainers are now writing small guides to what’s necessary, and where new and changed code should go. These documents, called walkthroughs, draw on their familiarity with the code and the community to steer newcomers to the “problem spaces” in the codebase that could use their help.

Walkthroughs lie somewhere between user stories and project documentation, serving as pointers to where a contributor can start to add value to the project, without requiring significant handholding. After all, most open source contributors are experienced developers who are donating their experience to the wider community, and who are working on their own schedule and on their own time.

What is a walkthrough?

Walkthroughs are high-level descriptions of the problem and the code intended to give contributors the necessary context to get started. They’re designed to provide a “mental map” of the relevant code, providing pointers to files, methods, and definitions. Other elements in a walkthrough might be links to pull requests that implement similar functionality, or that work with the same section of code, as well code snippets or pseudo code.

While walkthroughs can be documents in their own right, and included as part of project documentation, they can instead be something as simple as a comment in an issue discussion. That shouldn’t be surprising: Microsoft’s approach to open source is strongly linked to GitHub’s social coding model. The company is taking advantage of the same tools to add formatted walkthroughs using basic Markdown features to highlight key elements that can help developers navigate code. Walkthroughs can even include animated GIFs to illustrate expected UI behaviors where needed.

Although walkthroughs are a relatively informal approach to project management, there is some structure to how walkthroughs are written. You can think of them as an initial set of steps to solving a problem, much like a conversation with a development lead or a brainstorming session around a whiteboard.

Assigning walkthroughs to project boards

One interesting aspect of using walkthroughs in GitHub is the ability to assign them to a project. This allows you to add them to project boards, where you can add metadata to the walkthrough, such as to note difficulties, assign issues to users, and detail the resulting pull requests.

What began as a simple way of providing context for a feature request or a bug fix is now a basic project management tool, while still keeping an appropriate level of informality. There’s no requirement for a contributor to track the resulting project. It’s purely a tool for the maintainer, allowing them to see which walkthroughs are being worked on and which require more information to help contributors get started.

Building code by telling stories

Walkthroughs are an interesting example of project storytelling. Microsoft has a long history of using narrative techniques internally as a way of producing a shared understanding of a problem and its possible solutions. These narratives work at a higher level than agile development methodologies, often describing desired end states as well as the possible users for the feature.

By taking this approach outside the formal structures of corporate development, Microsoft is aiming both to provide shortcuts to where code needs to go in the project and to motivate possible contributors. It’s often daunting to look at an issue on GitHub without understanding the context of the problem and the code. What might be a trivial problem to solve often depends on having a deep knowledge of the code base, knowing what module to work with and which resources to modify.

Walkthroughs are a nicely informal, easy-to-grasp approach that doesn’t push contributors away, instead providing just the information they need to get started without underestimating their initiative and expertise. That’s an important requirement for any tool used by maintainers, as the worst possible outcome for any project is alienating volunteers.

Hopefully more open-source projects will pick up this technique, both inside and outside Microsoft. It’s a technique that could help the next generation of contributors get over the hurdle of building their first pull request.