Gitlab hero border pattern left svg Gitlab hero border pattern right svg


On this page

On Design and Writing

As'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 themselves 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 decisions 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).


Security must be looped in whenever changes are made to any of the following areas:

  1. Processing credentials/tokens
  2. Storing credentials/tokens
  3. Logic for privilege escalation
  4. Authorization logic
  5. User/account access controls
  6. Authentication mechanisms
  7. Abuse-related activities

Design Directory