Conway’s Law applies to your documentation, too

Almost 60 years ago, Melvin Conway wrote what we now call “Conway’s Law”:

[O]rganizations which design systems (in the broad sense used here) are constrained to produce designs which are copies of the communication structures of these organizations.

Melvin Conway

I hear Conway’s Law invoked most often in the context of application design. Critics say the design of applications or services give you a pretty reliable org chart. Users, of course, don’t care about the structure of the organization, they just want to use the software.

But I think the most glaring place that Conway’s Law shows up is in project documentation. This gets worse for larger open source projects, where there are semi-autonomous subprojects that maintain their own documentation. Sometimes the user-facing documentation is maintained by a dedicated documentation team and so can smooth over some of the “docs as org chart” problem. Other times, subprojects maintain their own user documentation and the documentation team just glues them together.

Fedora has a good example of the former case. The user documentation is coordinated by a small documentation team and the contributor documentation is self-maintained by individual teams within the larger project. So while the user documentation is focused on what users want to know (particularly the task-oriented Quick Docs), the contributor documentation is less discoverable. This doesn’t matter so much if you already know where you’re going, but it’s hard for new would-be contributors to figure out.

That’s why I really like the new GNOME Project Handbook. As Allan Day said in his blog post introducing the Handbook:

Those docs aren’t just important for practical information on how to contribute (though that is important). They’re also important when it comes to understanding the more general aspects of a project, like how decisions are made, who the stakeholders are, what the history is, and so on. For new contributors, understanding these aspects of a project is essential to being able to participate. (They are also the aspects of a project that established contributors often take for granted.)

Allan Day

Counteracting Conway’s Law is ultimately a fight against entropy. In order to keep your documentation from falling into the Conway trap, you have to actively curate it across the entire project. Even if it’s just a useful table of contents to the individually-maintained pieces.

This post’s featured photo by Alvaro Reyes on Unsplash.