Skip to content

Architecture Design Documentation

This document is a guide to how we do architecture design. At Trially, we believe in experimentation and iteration as the main drivers of our development process. As a project grows in complexity and organic iterative work can start to fall into entropy. This is where having a well defined architecture design documentation can help to ensure that there is alignment on the long term vision of a project.

Design documents

Design documents are version-controlled documents that define a long-term vision and a set of principles that guide implementation. They are living documents that start simple and expand as more is learned about the project. Below are the sections that usually exist in a design document:

Executive Summary

This section should:

  1. Be clear and understandable to all audiences
  2. Provide a comprehensive overview in one paragraph or more
  3. Capture the essence of your proposal

Key points:

  • Assume this may be the only section some people read
  • Focus on clarity and accessibility of information

Motivation and Goals

This section should:

  1. Explain why this change is important
  2. List specific goals and non-goals
  3. Highlight benefits to users

Key points:

  • Optionally link to issues showing interest
  • Consider referencing competing products to show gaps

Clearly articulates the driving forces behind your proposal and what it aims to achieve (or not achieve).

Proposal

This section should:

  1. Clearly state what you're proposing
  2. Keep it simple and high-level
  3. Provide enough detail for reviewers to understand

Key points:

  • Focus on the 'what', not the 'how'
  • Avoid detailed API designs or implementation specifics
  • Consider listing pros and cons for easy comparison with alternatives

Save the in-depth technical details for the "Design and Implementation Details" section.

Design and Implementation Details

This section should:

  1. Explain your change clearly
  2. Include API specs or code snippets if needed
  3. Discuss any ambiguities in implementation

Key points:

  • Provide enough context for understanding
  • Add implementation details as you progress
  • Document important technical decisions and their context
  • Include excalidraw diagrams or images if helpful

The level of detail depends on the proposal's complexity and impact. Major decisions warrant more documentation.

Implementation

Once the design document is complete and approved, we begin the implementation process. We begin the process by creating a new Linear project and manufacturing a team around it. This team will be the main driver of the implementation. Once the project start, we create a #wg- slack channel and add the team to it.