Design docs at Google

One of the key elements of Google’s software engineering culture is the use of defining software designs through design docs. These are relatively informal documents that the primary author or authors of a software system or application create before they embark on the coding project. The design doc documents the high level implementation strategy and key design decisions with emphasis on the trade-offs that were considered during those decisions.

As software engineers our job is not to produce code per se, but rather to solve problems. Unstructured text, like in the form of a design doc, may be the better tool for solving problems early in a project lifecycle, as it may be more concise and easier to comprehend, and communicates the problems and solutions at a higher level than code.

Besides the original documentation of a software design, design docs fulfill the following functions in the software development lifecycle:

  • Early identification of design issues when making changes is still cheap.
  • Achieving consensus around a design in the organization.
  • Ensuring consideration of cross-cutting concerns.
  • Scaling knowledge of senior engineers into the organization.
  • Form the basis of an organizational memory around design decisions.
  • Acts as a summary artifact in the technical portfolio of the software designer(s).

Refer Content-Structure

  • Context and scope
  • Goals and none-goals
    • define the problem clearly
  • The Actual Design
    • start with overview and then into details
    • write down the trade-offs throw design & key decisions
  • System context diagrams
    • use UML for software modelings
  • API design
  • data-storage design
  • Code and pesudo code

Other considerations

  • 阐明设计的决策过程和演绎过程是很重要的，发掘背后决策的根因是设计文档需要重点关注的。
  • 多因子关注，让更多领域专家的视野切入，好的设计应该经过更多因子的权衡
  • 文档不要太长，适度，要明白简单即是美
  • 适度考虑维护一个设计文档的 life-cycle，特别是对需要持续性维护的 doc
  • 方案设计的 Review 应该基于该文档进行
  • 持续演进，持续变化，持续学习

参考