Start working on the draft post

rauhala.info/posts/2022-08-19-design-docs.md

@@ -0,0 +1,41 @@
+---
+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.