chore(#1385): Create design docs guidelines (#1391)

Co-authored-by: Gareth Bowen <gareth@medic.org>

content/en/contribute/code/design-docs.md

@@ -0,0 +1,67 @@
+---
+title: "Design Documents Guide"
+linkTitle: "Design Docs"
+weight: 12
+description: >
+  Guidelines for writing technical design documents
+---
+
+## What are design docs?
+Software development is not just about writing code, but rather about solving problems and building the right solutions. Before diving into an initiative or feature and starting coding, it’s essential that the developers (and other team members) have a high-level understanding of what a solution might look like. 
+
+Design docs are informal documents that the leading developer of a certain piece of software creates before they start the actual coding of a solution. The design doc contains high-level technical design decisions and alternatives that were considered when making those decisions. 
+
+## Why write design docs?
+
+Besides being an excellent way of documenting software design, design docs come with several additional benefits:
+
+* Involve the team early and get feedback before implementation, after which changes are more difficult.
+* Identify solution concerns and issues rapidly, as making changes to a solution in the design phase is faster.
+* Provide a fantastic way to document technical decisions, which benefits the team, the community, and future contributors.  
+* Ensure the consideration of alternative solutions, assumptions and eventual constraints.
+* Achieve consensus in the team around the design and get everyone on the same page.
+
+## What could a design doc contain?
+
+The design doc can be added to the GitHub issue related to the feature or initiative to be implemented or in a Google Doc. 
+
+The list below contains a non-exhaustive list of items a design doc could cover.
+
+#### Context
+An overview of the context in which the piece of software is being built and what is actually being built. It's important to keep this section succint as it's only meant to bring the readers up to speed with the background facts.
+
+#### Goals and scope
+A short list of what the goals of the piece of software are, and, very importantly, what is out of scope. The out of scope items are explicitly chosen not to be goals, as for example "FHIR compliace of the API". Please note that a solution could cover out of scope items, as long as it doesn’t introduce trade-offs that prevent achieving the goals.
+
+#### Proposed solution
+The details of the solution that was chosen for implementation. This flexible-format section can contain how the developer envisions to code the solution, diagrams, sample code, pseudo-code, security considerations, and references to similar solutions or frameworks to be used. It's important that this section explains why this particular solution best satisfies the goals.
+
+#### Alternative solutions considered
+A list of alternative designs that would have achieved similar outcomes, together with the trade-offs that each respective design makes and how those trade-offs led to the decision to select the proposed solution.
+
+#### Assumptions
+A description of the assumptions made, for example user interface design or general system characteristics (e.g. operating systems).
+
+#### Constraints
+These can include constraints such as security, scalability, or performance.
+
+#### Open questions
+Any open issues that you aren’t sure about, or suggested future work.
+
+[This example](https://docs.google.com/document/d/1bR3jygKQvfIK1CkRaplxz4LyXQqgO21MTjy8Jsd6s6c/edit?usp=sharing) shows how a design doc could look like.
+
+{{% alert title="Remember" %}}
+* Keep it simple and concise, write just enough documentation. Design docs should be sufficiently detailed but succint enough to actually be read by busy people.
+* Be clear: Don't use unnecessarily complicated language and simplify whenever you can.
+* Make important points stand out (for example, in bold letters).
+{{% /alert %}}
+
+## When not to write a design doc
+
+Writing design docs takes time and energy. When deciding to whether write a design doc or not, it's essential to reflect on the core trade-off of whether the benefits in the alignment around technical design, documentation, senior review, outweigh the extra work of actually creating the doc. If a doc basically says "This is how I am going to implement this feature" without going into trade-offs, alternatives, and explaining decision making (or if the solution is so obvious that there were no trade-offs), then it would probably have been a better idea to write the actual code right away instead of going through the effort of putting together a design doc.
+
+Often, the overhead of creating and reviewing a design doc may not be compatible with prototyping and fast iteration. If "you tried it out and it worked", it might mean that you already have a solution that's worth pursuing without having to write a document. However, it's important to remember that subscribing to agile methodologies and fast iteration is not an excuse for not taking the time to get solutions to known problems right. 
+
+## More info
+
+This policy was inspired by [Design docs guidelines at Google](https://www.industrialempathy.com/posts/design-docs-at-google/).

content/en/contribute/code/repository-checklist.md

@@ -1,7 +1,7 @@
 ---
 title: "CHT Product Repository Checklist"
 linkTitle: "CHT Product Repository Checklist"
-weight: 5
+weight: 8
 description: >
   Checklist to consider when creating CHT Product repositories under Medic's GitHub organization account
 ---

content/en/contribute/code/static-analysis.md

@@ -1,7 +1,7 @@
 ---
 title: "Static Analysis"
 linkTitle: "Static Analysis"
-weight: 9
+weight: 11
 description: >
   Guidelines for static analysis of CHT code.
 ---

content/en/contribute/code/using-npm.md

@@ -1,7 +1,7 @@
 ---
 title: "Using NPM"
 linkTitle: "Using NPM"
-weight: 9
+weight: 10
 description: >
   Quick guide to using NPM
 aliases: >