Home > technical > The Repo Of Shared Understanding

The Repo Of Shared Understanding

Documentation can be organized, structured, archived, searched. Verbal communications can’t.

Check out these two communication system configurations for developing software.

Shared Repo

The system on the left, which depends (almost) solely on face-to-face collaboration, is the “agile” way. The system on the right, designed around a living, breathing, Repository Of Shared Understanding (ROSU) and supplemented by face-to-face conversation, is the “traditional” configuration.

As the previous paragraph implies, “agile” doesn’t recommend no documentation generation. It simply relegates the practice of document creation to the back of the bus. The idea, premised on the myth that documentation isn’t a required deliverable (in my industry it is) and the truth that programmers hate to write anything but code, is to supplement face-to-face communion with temporary, discardable, napkin scribblings and incomprehensible whiteboard snapshots.

WB Sketches

Which system configuration do you think is more scalable? Which is more effective for long-lived, software-intensive products? Which do you think is better, more accommodating, for onboarding future team members? Which do you think is more effective for investigating/understanding/debugging system level failures (not unit level failures)?

Agilists will often bolster their “minimal documentation” approach with the assertion that requirements and design documents become obsolete as soon as the ink dries. Well yeah, if the team doesn’t continuously update its ROSU, then they’re right. But why is it such a big deal to keep the ROSU in synch with the code?  The big deal is that it’s tough to sustain the discipline and resolve to so.

Categories: technical
  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: