Design

On this page

On Design and Writing

As GitLab.com's levels of functionality and scale increase, so does its complexity. A disciplined approach to meet the challenges presented by said complexity is necessary so we can frame technical discussions and increase the leverage on technical decisions: design.

The late Andy Grove's High Output Management highlights his thinking on business reports as an information medium, and these thoughts apply to design as well:

As [design] is formulated and written, authors are forced to be more precise than they might verbally. Hence, their value stems from the discipline and the thinking the writers are forced to impose upon theselves and they identify and deal with trouble spots in their presentation. [Designs] are more a medium of self-discipline than a way to communicate information. Writing the design is important; reading may not be so as much.

Reading is, of course, important, as it drives information and knowledge sharing as well as healthy technical discussions. This makes the writing vital. Design clarifies and scopes the problem, drives productive discussions, and presents decisons concisely.

Also from the same book:

All production flows have a basic characteristic: the material becomes more valuable as it moves through the process. […] A common rule we should always try to heed is to detect and fix any problems in a production process at the lowest-value stage possible.

Thus, early scoping and design is a valuable investment.

Design is not intended to force all decisions up front but to methodically drive them. Time invested in design eliminates confusion and ambiguity, particularly as it relates to scope, and ensures specific aspects of the engineering work we perform take place (monitoring being one obvious case).

Workflow

Design Directory