42 lines
1.9 KiB
Markdown
42 lines
1.9 KiB
Markdown
|
---
|
||
|
title: Design Documents
|
||
|
tags: design
|
||
|
---
|
||
|
|
||
|
We had a problem at work some time ago, with implementing features faster than
|
||
|
we could refine new items. The roadmap was a mile long, but the quality of our
|
||
|
work items left a lot to desire. The solution was to have more concerted effort
|
||
|
into the act of designing and refining. One part of this effort was the
|
||
|
introduction of design documents to our workflow.
|
||
|
|
||
|
[Design Documents at Google](https://www.industrialempathy.com/posts/design-docs-at-google/)
|
||
|
|
||
|
![](/images/sample-designdoc.png)
|
||
|
|
||
|
We have been experimenting on using design documents for a little over half a
|
||
|
year now and have been able to refine them to suit our processes quite nicely.
|
||
|
Feel free to read the article above, it's a concise explanation on how they're
|
||
|
using design documents, and what I'm going to write is going to focus on a
|
||
|
subset of the article, on the aspects that I have found to be important.
|
||
|
|
||
|
## What are design documents
|
||
|
|
||
|
![stakeholder-architect-design-loop](/images/stakeholder-architect-design.png)
|
||
|
|
||
|
When designing a new feature, the stakeholders have a set of requirements they
|
||
|
need fulfilled. The product owner collects the requirements and provides them
|
||
|
to the architect to be solved. It's this solution, that needs to be portrayed
|
||
|
by the design document. The design document should portrey the high-level view
|
||
|
of the design, without implementation details, in a way that the developers can
|
||
|
take the design and implement a concrete solution.
|
||
|
|
||
|
### What should the design document contain
|
||
|
|
||
|
> A feature to add items to a shopping cart. The items needs to be reserved in
|
||
|
the backend so that the reservation is synced across different users.
|
||
|
|
||
|
The design document should be written on a high level, it should explain the
|
||
|
problem and it should explain the solution for it, but it should not be the
|
||
|
implementation guide. The design document should not contain any code or
|
||
|
pseudocode in it.
|