Tell Request wot Tell Request

An improved pull request experience (on Github)!

A Tell Request is a collection of comments and visual cues applied to a pull request, presented in a suggested viewing order. You are asking someone to let you tell them about your changes before they pull.

Code review is integral to modern software development and yet is often an afterthought or a chore: from the writer's perspective responsibility is sometimes taken to end with pushing the new code; from the reader's perspective it can be daunting to be presented with a set of changes and be expected to figure out how it all fits together.

Modern tooling attack the problem in very dry ways that are artifacts of the underlying tech, for example diffs and commits, which provide a lot of information locally, but do a poor job of telling you how each piece connects in the larger whole - think of how people solve jigsaw puzzles: initially, knowing a piece is part of the skyline is more helpful than its specific contour.

A tell request is all about providing a tour of the changes that is as much about pointing things out as it is about the order in which you do so. Think of a slideshow inlined within a set of diffs.