The Software Architect Elevator

Chapter 18. Explaining Stuff

Build a Ramp for the Reader, Not a Cliff!

Build a ramp, not a cliff for the reader—by Miu Tsutsui

Martin Fowler occasionally introduces himself as a guy “who is good at explaining things.” Although this certainly has a touch of British Understatement™, it also highlights a critically important but rare skill in IT. Too often technical people either produce an explanation at such a high level that it is almost meaningless or spew out reams of technical jargon with no apparent rhyme or reason.

Build a Ramp, Not a Cliff

A team of architects once presented a new hardware and software stack for high-performance computing to a management steering committee. The material covered everything from workload management down to storage hardware. It contrasted vertically integrated stacks like Hadoop and Hadoop Distributed File System (HDFS) against standalone workload management solutions like Platform Load Sharing Facility (LSF). In one of the comparison slides, “POSIX compliance” jumped out as a selection criteria. While this may be entirely appropriate, how do you explain to someone who knows little about filesystems what this means, why it is important, and what the ramifications are?

We often refer to learning curves as steep, meaning it is tough for newcomers to become familiar with, or “ramp up” on, a new system or tool. I tend to assume my executive audience ...