diff --git a/rauhala.info/images/sample-designdoc.png b/rauhala.info/images/sample-designdoc.png new file mode 100644 index 0000000..258316f Binary files /dev/null and b/rauhala.info/images/sample-designdoc.png differ diff --git a/rauhala.info/images/stakeholder-architect-design.png b/rauhala.info/images/stakeholder-architect-design.png new file mode 100644 index 0000000..ac00549 Binary files /dev/null and b/rauhala.info/images/stakeholder-architect-design.png differ diff --git a/rauhala.info/posts/2022-08-19-design-docs.md b/rauhala.info/posts/2022-08-19-design-docs.md new file mode 100644 index 0000000..a04e7f8 --- /dev/null +++ b/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.