> Your readers are not determined invaders. They want the interface to suffice. Give them a bit of explanatory distance, and they'll find a reason to turn back.
This also gives credence to cascading explanations for a codebase. I only want to plumb the depths if I'm starting from the top, or rise a few levels if I'm starting from the bottom, until I have a sufficient mental model to move forward. Rarely, in the context of producing code or reviewing it, am I looking to understand the entire system in that instant.
> Your readers are not determined invaders. They want the interface to suffice. Give them a bit of explanatory distance, and they'll find a reason to turn back.
This also gives credence to cascading explanations for a codebase. I only want to plumb the depths if I'm starting from the top, or rise a few levels if I'm starting from the bottom, until I have a sufficient mental model to move forward. Rarely, in the context of producing code or reviewing it, am I looking to understand the entire system in that instant.