diff --git a/docs/content/docs/adr.md b/docs/content/docs/adr.md
index e5afdd9..6da8d57 100644
--- a/docs/content/docs/adr.md
+++ b/docs/content/docs/adr.md
@@ -1,143 +1,143 @@
----
-title: ADR
-description: >
- Architecture decisions are important and you should probably track them.
-weight: 9
-date: '2021-11-04'
-author: Romain Vasseur
----
-
-As we stated before, there is no per say bad choices, provided that you can explain why you made it.
-A choice can appear to be unlucky or inappropriate if we analyze it through our current perspective, but can make sense if we do it via past prism.
-Thus, the importance of tracking those choices to be able to rewind and replay without be tempting to rewrite the history.
-Of course, this applies to many domains, especially History. Let's see how it fits into software crafting.
-
-## The What & The How
-
-You start a project by defining its purpose, WHAT issue it will solve, WHAT service it will provide, ...
-Once done comes the 2nd stage, the HOW. HOW will you do that? HOW will you deliver this? ...
-
-As usual, issues quickly arise, namely when you discover a WHAT can be achieved by many HOW.
-Then, it is important to explain why you pick this particular HOW among other siblings.
-
-{{% cardpane %}}
-
-{{% card header="**Travel**" %}}
-
-Assuming you would like to travel for holidays. With friends. Every one towards a single relaxing place. This is the WHAT.
-{{% /card %}}
-
-{{% card header="**Plan**" %}}
-
-Some will go by plane, some other by car. Some will stage the journey, stopping-off every city in the middle. Some others will choose to travel by night. And so on. This is the HOW.
-And it is important to explain why those decisions were made eg plane makes me sick, or nighttime passage is cheaper. And so on.
-{{% /card %}}
-
-{{% /cardpane %}}
-
-## Architecture Decision Record
-
-Log sizable decision making during project lifecycle is a good habit. As for other satellite artifacts like dependencies listing (and their induced licensing model), it complements very well the documentation side. And contribute to story-telling. **ADR** comes with multiple flavors, more or less complicated. As usual, start gently and complexify only if needed. It is commonly used to leverage the 6 following traits.
-
-{{% cardpane %}}
-
-{{% card header="**Identity**" %}}
-
-Each ADR deserves a proper name. Make it unambiguous. It is also common to index them to support timeline discussion.
-{{% /card %}}
-
-{{% card header="**Date**" %}}
-
-Most of the project we work on stretch out over several months. It is thus important to track when we make decision to be able to contextually correlate later on.
-{{% /card %}}
-
-{{% card header="**Status**" %}}
-
-Decision making is a process. As for every process, it is important to track the status, and keep full history including ideas that were refused. They often help further brain storming.
-{{% /card %}}
-
-{{% /cardpane %}}
-
-{{% cardpane %}}
-
-{{% card header="**Context**" %}}
-
-Take time to specify the context which leads to this decision process. Are we experiencing bottlenecks or issues? Would we like to ensure that we will avoid those pitfalls?
-{{% /card %}}
-
-{{% card header="**Decision**" %}}
-
-Explain your choice. Provide insights if you pick a choice within multiple offer. Stress out if you fallback rather than choose (eg for cost reason).
-{{% /card %}}
-
-{{% card header="**Consequence**" %}}
-
-Every single decision may have impact on the project, on the team, on your daily life. Foresee consequences of a choice is a good habit. And ensure every one agree upon both decision & consequence(s).
-{{% /card %}}
-
-{{% /cardpane %}}
-
-## Hands-on, the C4 journey
-
-Find below the hypothetic ADR subset relative to C4 one could end up with on a given project.
-
-{{% cardpane %}}
-
-{{% card header="**001. Use C4 model**" %}}
-
-* 05/08/2020
-* Accepted
-* Project architecture is complex and must be regularly discussed with heterogenous audience. We lack both diagramming convention and unified model.
-* Leverage C4 model to describe architecture. UML is too complex & thus rejected.
-* Streamline C4 usage, starting with tech leads. Provide tooling.
-{{% /card %}}
-
-{{% card header="**005. Strengthen C4 tooling**" %}}
-
-* 07/11/2020
-* Accepted
-* C4 model has been broadly accepted but is costly to put in place due to lack of tooling
-* Enrich corporate diagramming solution with C4 facilities. Define guidelines to group & sort diagramming within libraries.
-* Raise team members awareness. Ask for licensing. Promote tool by systemizing usage during tool specs & reviews.
-{{% /card %}}
-
-{{% card header="**018. Code-first approach**" %}}
-
-* 09/18/2021
-* Proposed
-* We experience difficulty over past months to properly scale the sketch-first approach. Maintenance cost is high. Diagramming are uncoupled from source code.
-* Gradually switch from sketch-first approach to code-first one leveraging dedicated tooling.
-* Introduce migration to teams. Once again leverage local champion to lead changes. Ask for licensing. Create workstream to gather & process team needs on that matter.
-{{% /card %}}
-
-{{% /cardpane %}}
-
-Obviously, ADR are simplified there. You are likely to end up with more details for context, decision & consequences. Remember as well that ADR should be part of our project, obeying the same workflow (branching, PR, reviews) and enforcing our repository as the only source of truth. A good approach is to create a dedicated file per ADR, sticking to markdown or equivalent format ie human readable and version control friendly.
-
-## Analysis
-
-Once again, we do not store & track for the sake of storing & tracking. Data are there to be explored and to support us in our endless journey to improve workflow. Thus, it is important to be able to generate views as well. ADR becomes another code-first approach model one can query to surface consolidated metrics. Find below some views that are provided by Structurizr suite.
-
-{{% cardpane %}}
-
-{{% card header="**Timeline**" %}}
-
-Timeline view to correlate with project lifecycle eg do we make more decisions during design phase or hardening one? How sustainable our decisions are?
-{{% /card %}}
-
-{{% card header="**Correlation**" %}}
-
-Timeline view focusing (arbitrarily) on year but highlighting ADR name. Could be used in conjunction with the previous one. Could be great to sketch a pattern from the sequence of status. Full green sequence highlights Mojo momentum. Green & red interleaves may highlight uncertainty or paradigm inversion.
-{{% /card %}}
-
-{{% card header="**Graph**" %}}
-
-Graph view to materialize ADR coupling eg relationship or lineage (accepted -> superseded). Can be helpful to rewind the journey or to start a brand-new project ie directly starting with leaves.
-{{% /card %}}
-
-{{% /cardpane %}}
-
-## Closing
-
-We saw in this module why recording architecture decisions does matter.
+---
+title: ADR
+description: >
+ Architecture decisions are important and you should probably track them.
+weight: 9
+date: '2021-11-04'
+author: Romain Vasseur
+---
+
+As we stated before, there is no per say bad choices, provided that you can explain why you made it.
+A choice can appear to be unlucky or inappropriate if we analyze it through our current perspective, but can make sense if we do it via past prism.
+Thus, the importance of tracking those choices to be able to rewind and replay without be tempting to rewrite the history.
+Of course, this applies to many domains, especially History. Let's see how it fits into software crafting.
+
+## The What & The How
+
+You start a project by defining its purpose, WHAT issue it will solve, WHAT service it will provide, ...
+Once done comes the 2nd stage, the HOW. HOW will you do that? HOW will you deliver this? ...
+
+As usual, issues quickly arise, namely when you discover a WHAT can be achieved by many HOW.
+Then, it is important to explain why you pick this particular HOW among other siblings.
+
+{{% cardpane %}}
+
+{{% card header="**Travel**" %}}
+
+Assuming you would like to travel for holidays. With friends. Every one towards a single relaxing place. This is the WHAT.
+{{% /card %}}
+
+{{% card header="**Plan**" %}}
+
+Some will go by plane, some other by car. Some will stage the journey, stopping-off every city in the middle. Some others will choose to travel by night. And so on. This is the HOW.
+And it is important to explain why those decisions were made eg plane makes me sick, or nighttime passage is cheaper. And so on.
+{{% /card %}}
+
+{{% /cardpane %}}
+
+## Architecture Decision Record
+
+Log sizable decision making during project lifecycle is a good habit. As for other satellite artifacts like dependencies listing (and their induced licensing model), it complements very well the documentation side. And contribute to story-telling. **ADR** comes with multiple flavors, more or less complicated. As usual, start gently and complexify only if needed. It is commonly used to leverage the 6 following traits.
+
+{{% cardpane %}}
+
+{{% card header="**Identity**" %}}
+
+Each ADR deserves a proper name. Make it unambiguous. It is also common to index them to support timeline discussion.
+{{% /card %}}
+
+{{% card header="**Date**" %}}
+
+Most of the project we work on stretch out over several months. It is thus important to track when we make decision to be able to contextually correlate later on.
+{{% /card %}}
+
+{{% card header="**Status**" %}}
+
+Decision making is a process. As for every process, it is important to track the status, and keep full history including ideas that were refused. They often help further brain storming.
+{{% /card %}}
+
+{{% /cardpane %}}
+
+{{% cardpane %}}
+
+{{% card header="**Context**" %}}
+
+Take time to specify the context which leads to this decision process. Are we experiencing bottlenecks or issues? Would we like to ensure that we will avoid those pitfalls?
+{{% /card %}}
+
+{{% card header="**Decision**" %}}
+
+Explain your choice. Provide insights if you pick a choice within multiple offer. Stress out if you fallback rather than choose (eg for cost reason).
+{{% /card %}}
+
+{{% card header="**Consequence**" %}}
+
+Every single decision may have impact on the project, on the team, on your daily life. Foresee consequences of a choice is a good habit. And ensure every one agree upon both decision & consequence(s).
+{{% /card %}}
+
+{{% /cardpane %}}
+
+## Hands-on, the C4 journey
+
+Find below the hypothetic ADR subset relative to C4 one could end up with on a given project.
+
+{{% cardpane %}}
+
+{{% card header="**001. Use C4 model**" %}}
+
+* 05/08/2020
+* Accepted
+* Project architecture is complex and must be regularly discussed with heterogenous audience. We lack both diagramming convention and unified model.
+* Leverage C4 model to describe architecture. UML is too complex & thus rejected.
+* Streamline C4 usage, starting with tech leads. Provide tooling.
+{{% /card %}}
+
+{{% card header="**005. Strengthen C4 tooling**" %}}
+
+* 07/11/2020
+* Accepted
+* C4 model has been broadly accepted but is costly to put in place due to lack of tooling
+* Enrich corporate diagramming solution with C4 facilities. Define guidelines to group & sort diagramming within libraries.
+* Raise team members awareness. Ask for licensing. Promote tool by systemizing usage during tool specs & reviews.
+{{% /card %}}
+
+{{% card header="**018. Code-first approach**" %}}
+
+* 09/18/2021
+* Proposed
+* We experience difficulty over past months to properly scale the sketch-first approach. Maintenance cost is high. Diagramming are uncoupled from source code.
+* Gradually switch from sketch-first approach to code-first one leveraging dedicated tooling.
+* Introduce migration to teams. Once again leverage local champion to lead changes. Ask for licensing. Create workstream to gather & process team needs on that matter.
+{{% /card %}}
+
+{{% /cardpane %}}
+
+Obviously, ADR are simplified there. You are likely to end up with more details for context, decision & consequences. Remember as well that ADR should be part of our project, obeying the same workflow (branching, PR, reviews) and enforcing our repository as the only source of truth. A good approach is to create a dedicated file per ADR, sticking to markdown or equivalent format ie human readable and version control friendly.
+
+## Analysis
+
+Once again, we do not store & track for the sake of storing & tracking. Data are there to be explored and to support us in our endless journey to improve workflow. Thus, it is important to be able to generate views as well. ADR becomes another code-first approach model one can query to surface consolidated metrics. Find below some views that are provided by Structurizr suite.
+
+{{% cardpane %}}
+
+{{% card header="**Timeline**" %}}
+
+Timeline view to correlate with project lifecycle eg do we make more decisions during design phase or hardening one? How sustainable our decisions are?
+{{% /card %}}
+
+{{% card header="**Correlation**" %}}
+
+Timeline view focusing (arbitrarily) on year but highlighting ADR name. Could be used in conjunction with the previous one. Could be great to sketch a pattern from the sequence of status. Full green sequence highlights Mojo momentum. Green & red interleaves may highlight uncertainty or paradigm inversion.
+{{% /card %}}
+
+{{% card header="**Graph**" %}}
+
+Graph view to materialize ADR coupling eg relationship or lineage (accepted -> superseded). Can be helpful to rewind the journey or to start a brand-new project ie directly starting with leaves.
+{{% /card %}}
+
+{{% /cardpane %}}
+
+## Closing
+
+We saw in this module why recording architecture decisions does matter.
By reusing what we learned before, namely defining a model & agreeing upon convention, it becomes straightforward to surface custom views to explore and analyze data. Trying hard to grasp what we did well and what we did wrong is the best way to improve upcoming projects. Do not miss opportunity to leverage modern approach & efficient tooling to support you on this challenging journey.
\ No newline at end of file
diff --git a/docs/content/docs/c4-model.md b/docs/content/docs/c4-model.md
index 3aa4713..82dd76b 100644
--- a/docs/content/docs/c4-model.md
+++ b/docs/content/docs/c4-model.md
@@ -1,119 +1,119 @@
----
-title: C4 Model
-description: >
- Gentle 101 covering core concepts.
-weight: 2
-date: '2021-11-02'
-author: Romain Vasseur
----
-
-## Status
-
-{{% alert color="warning" %}}
-Ask somebody in the building industry to visually communicate the architecture of a building and you'll be presented with site plans, floor plans, elevation views, cross-section views and detail drawings. In contrast, ask a software developer to communicate the software architecture of a software system using diagrams and you'll likely get a confused mess of boxes and lines … inconsistent notation (color coding, shapes, line styles, etc.), ambiguous naming, unlabeled relationships, generic terminology, missing technology choices, mixed abstractions, etc.
-Simon Brown
-{{% /alert %}}
-
-## Philosophy
-
-{{% alert color="warning" %}}
-There are many different audience for diagrams and documentation, all with different interest.
-Simon Brown
-{{% /alert %}}
-
-Thus, the necessity to end up with a so called _Ubuiquitous language_ for diagramming to support & improve discussion.
-Let's introduce the pillars the **C4 model** (created by Simon Brown) is based upon.
-
-## Zoom levels
-
-With ever-growing & complex ecosystems, it becomes unmanageable to end up with a single picture that can both exhaustively capture the whole scope and be properly processed by standard human being. When facing such a situation, splitting the overall problem into chunks or layers, which focus on a dedicated set of aspects instead, is a common way to address the issue.
-Humanity has been treating geographical maps this way (Continent, Country, Region, Local) for centuries.
-
-
-
-The C4 model is no exception and introduces 4 different zoom levels, hence the name:
-
-| ID | Name | Description |
-|-|-|-|
-| C4.1 | **C**ontext | Focuses on personas and software systems rather than technologies, protocols and other low-level details. |
-| C4.2 | **C**ontainer | Focuses on the way a given system is broken down, and the induced relationships. Highlights relevant technology choice. |
-| C4.3 | **C**omponent | Materializes components that shapes a given container, refining technology choices and how everything articulates. |
-| C4.4 | **C**ode | Explains how a given component is chunked into projects or classes. |
-
-## Zoom consistency
-
-The main idea is to ease an element’s identification & coupling and to cluster/hide information details to the level it is pertinent to.
-
-Zoom levels are not mixed to avoid discrepancy e.g. a restaurant menu is:
-- either abbreviated
- ```
- starter
- main course
- dessert
- ```
-- or verbose
- ```
- starters (…, …, …)
- main courses (…, …, …)
- desserts (…, …, …)
- ```
-
-but rarely mixed like
-```
-starter
-main course
-desserts (…, …, …)
-```
-
-Once again, the same is true of the geographic maps we are used to.
-
-|||
-|-|-|
-||Typical international map. Notice how every country is fairly dealt with: name, color, boundary. No insights.|
-||If we focus on France, we usually end up with first level of granularity, known as region. Once again, fairness treatment.|
-||Zooming one last time to department layer. Notice how context is provided through gray neighboring without noising the focused area (the colored one). And once again, each department or dependency is equally processed. |
-
-It is vital to decrease mental workload to cluster information by introducing this level of consistency or treatment equity.
-
-## Navigation
-
-One issue that is never encountered when we stick to a "god"-diagram-like paradigm is the navigation one.
-As soon as we decide to split architecture into multiple diagrams or views, we have to provide an efficient way to navigate back and forth for the reader.
-As for monolith to micro-services migration, what we get in term of uncoupling must be paid back in terms of stitching.
-
-Most of us have already played with Google Earth and experienced how natural it is to pick a point on the globe, and seamlessly focus back and forth by zooming in and out accordingly. Same goes for our architecture materials.
-
-Consider the bunch of diagrams as Google Earth staples. Wherever you are, you could then just zoom in or out, and the view will react accordingly, either by refining area and providing more insights, or stepping back and hiding underlying irrelevant complexity.
-The noticeable difference with Google Earth lies in the fact our scroll wheel operates in discrete steps. Remember we have a finite number of indexed layers, and we cannot deal with 1.5 or 2.8 zoom level.
-
-## Recipe
-
-The main advantage of these metaphors is that they are easy to grasp regardless of the audience and thus, ease communication between technical folks & business guys while enforcing consistency.
-
-So, basically, what you should end up with, if you stick to the recipe exposed above is 4 layers with semantic content that you can easily navigate back and forth through and the content is contextually & smartly narrowed.
-
-
-
-Obviously, this diagram only renders one single system-container-component-code vertical slice. Real life projects are likely to be more complex. That is why it is important to first agree on some [conventions](/docs/convention) before engaging further...
-
-
-
-## Complementary diagram
-
-Sadly, sticking to only 4 levels is not enough to cover other strategic aspects architecture diagramming should deal with.
-Thus, `C4 model` introduces a bunch of complementary diagrams:
-
-| ID | Name | Description |
-|-|-|-|
-| C4.L | **L**andscape | Nowadays, system is likely to be part of a bigger thing, often referred as ecosystem. Landscape diagrams come in handy to fill this gap, zooming out from C4.1 (dedicated to a single system) to embrace the whole complexity, highlighting coupling, synergy and interactions of all actors. |
-| C4.W | **W**orkflow | Workflows, even simple ones, poorly accommodate the inherent static nature of diagram. It is used to leverage indexed actions to show case the dynamic of a usage. |
-| C4.D | **D**eployment | 4 main levels describe how a given system is made and can be broken down, w/o specifying how it will be deployed, as it is not relevant in that context. But to cope with this missing dimension, model proposes to tailor new kind of diagram that illustrate how systems and containers will be mapped to infrastructure.|
-
-
-
-## Closing
-
-In this session, we introduced the **C4 model** and its underlying concepts.
-We also sketched some raw diagrams to materialize what we should end up with.
-It is now time to agree on some conventions, prior to engage further.
+---
+title: C4 Model
+description: >
+ Gentle 101 covering core concepts.
+weight: 2
+date: '2021-11-02'
+author: Romain Vasseur
+---
+
+## Status
+
+{{% alert color="warning" %}}
+Ask somebody in the building industry to visually communicate the architecture of a building and you'll be presented with site plans, floor plans, elevation views, cross-section views and detail drawings. In contrast, ask a software developer to communicate the software architecture of a software system using diagrams and you'll likely get a confused mess of boxes and lines … inconsistent notation (color coding, shapes, line styles, etc.), ambiguous naming, unlabeled relationships, generic terminology, missing technology choices, mixed abstractions, etc.
+Simon Brown
+{{% /alert %}}
+
+## Philosophy
+
+{{% alert color="warning" %}}
+There are many different audience for diagrams and documentation, all with different interest.
+Simon Brown
+{{% /alert %}}
+
+Thus, the necessity to end up with a so called _Ubuiquitous language_ for diagramming to support & improve discussion.
+Let's introduce the pillars the **C4 model** (created by Simon Brown) is based upon.
+
+## Zoom levels
+
+With ever-growing & complex ecosystems, it becomes unmanageable to end up with a single picture that can both exhaustively capture the whole scope and be properly processed by standard human being. When facing such a situation, splitting the overall problem into chunks or layers, which focus on a dedicated set of aspects instead, is a common way to address the issue.
+Humanity has been treating geographical maps this way (Continent, Country, Region, Local) for centuries.
+
+
+
+The C4 model is no exception and introduces 4 different zoom levels, hence the name:
+
+| ID | Name | Description |
+|-|-|-|
+| C4.1 | **C**ontext | Focuses on personas and software systems rather than technologies, protocols and other low-level details. |
+| C4.2 | **C**ontainer | Focuses on the way a given system is broken down, and the induced relationships. Highlights relevant technology choice. |
+| C4.3 | **C**omponent | Materializes components that shapes a given container, refining technology choices and how everything articulates. |
+| C4.4 | **C**ode | Explains how a given component is chunked into projects or classes. |
+
+## Zoom consistency
+
+The main idea is to ease an element’s identification & coupling and to cluster/hide information details to the level it is pertinent to.
+
+Zoom levels are not mixed to avoid discrepancy e.g. a restaurant menu is:
+- either abbreviated
+ ```
+ starter
+ main course
+ dessert
+ ```
+- or verbose
+ ```
+ starters (…, …, …)
+ main courses (…, …, …)
+ desserts (…, …, …)
+ ```
+
+but rarely mixed like
+```
+starter
+main course
+desserts (…, …, …)
+```
+
+Once again, the same is true of the geographic maps we are used to.
+
+|||
+|-|-|
+||Typical international map. Notice how every country is fairly dealt with: name, color, boundary. No insights.|
+||If we focus on France, we usually end up with first level of granularity, known as region. Once again, fairness treatment.|
+||Zooming one last time to department layer. Notice how context is provided through gray neighboring without noising the focused area (the colored one). And once again, each department or dependency is equally processed. |
+
+It is vital to decrease mental workload to cluster information by introducing this level of consistency or treatment equity.
+
+## Navigation
+
+One issue that is never encountered when we stick to a "god"-diagram-like paradigm is the navigation one.
+As soon as we decide to split architecture into multiple diagrams or views, we have to provide an efficient way to navigate back and forth for the reader.
+As for monolith to micro-services migration, what we get in term of uncoupling must be paid back in terms of stitching.
+
+Most of us have already played with Google Earth and experienced how natural it is to pick a point on the globe, and seamlessly focus back and forth by zooming in and out accordingly. Same goes for our architecture materials.
+
+Consider the bunch of diagrams as Google Earth staples. Wherever you are, you could then just zoom in or out, and the view will react accordingly, either by refining area and providing more insights, or stepping back and hiding underlying irrelevant complexity.
+The noticeable difference with Google Earth lies in the fact our scroll wheel operates in discrete steps. Remember we have a finite number of indexed layers, and we cannot deal with 1.5 or 2.8 zoom level.
+
+## Recipe
+
+The main advantage of these metaphors is that they are easy to grasp regardless of the audience and thus, ease communication between technical folks & business guys while enforcing consistency.
+
+So, basically, what you should end up with, if you stick to the recipe exposed above is 4 layers with semantic content that you can easily navigate back and forth through and the content is contextually & smartly narrowed.
+
+
+
+Obviously, this diagram only renders one single system-container-component-code vertical slice. Real life projects are likely to be more complex. That is why it is important to first agree on some [conventions](/docs/convention) before engaging further...
+
+
+
+## Complementary diagram
+
+Sadly, sticking to only 4 levels is not enough to cover other strategic aspects architecture diagramming should deal with.
+Thus, `C4 model` introduces a bunch of complementary diagrams:
+
+| ID | Name | Description |
+|-|-|-|
+| C4.L | **L**andscape | Nowadays, system is likely to be part of a bigger thing, often referred as ecosystem. Landscape diagrams come in handy to fill this gap, zooming out from C4.1 (dedicated to a single system) to embrace the whole complexity, highlighting coupling, synergy and interactions of all actors. |
+| C4.W | **W**orkflow | Workflows, even simple ones, poorly accommodate the inherent static nature of diagram. It is used to leverage indexed actions to show case the dynamic of a usage. |
+| C4.D | **D**eployment | 4 main levels describe how a given system is made and can be broken down, w/o specifying how it will be deployed, as it is not relevant in that context. But to cope with this missing dimension, model proposes to tailor new kind of diagram that illustrate how systems and containers will be mapped to infrastructure.|
+
+
+
+## Closing
+
+In this session, we introduced the **C4 model** and its underlying concepts.
+We also sketched some raw diagrams to materialize what we should end up with.
+It is now time to agree on some conventions, prior to engage further.
Good news, that's what the next [session](/docs/convention) is all about.
\ No newline at end of file
diff --git a/docs/content/docs/code.md b/docs/content/docs/code.md
index fe1c6f7..a441f44 100644
--- a/docs/content/docs/code.md
+++ b/docs/content/docs/code.md
@@ -1,135 +1,135 @@
----
-title: Architecture as code
-description: >
- Deep dive code first approach, assets and drawbacks.
-weight: 6
-date: '2021-11-06'
-author: Romain Vasseur
----
-
-Previously, we saw that **sketch-first** approach, as appealing as it may look like, comes with painful drawbacks that can prevent sizable project to properly scale eg huge maintenance cost, human error prone, ...
-
-This post will give some insights of the **code-first** or **architecture as code** approach, stressing out pros and cons of such a method.
-It should be read in parallel with [previous one](/docs/sketch), which covers the **architecture as sketch** or **sketch-first** approach.
-
-As always, **YMMV**, so spend time to learn and experience prior to make your **own** decision.
-
-## Recipe
-
-|||
-|-|-|
-| Describe | Leveraging either an API or a DSL, 1st stage is to describe your model in an human-readable, source control friendly way. |
-| Parse & build | Next stage is the realm of parser, analyzer & builder which are in charge of ingesting & validating model description and transforming it into a operable model. |
-| Explore | Final stage is to provide ways/views to explore and display your model to fit audience need and support discussion. |
-
-## Model
-
-Instead of drag & dropping shapes & arrows, code-first approach implies to write code. Amazing.
-A model can be defined as a set of types, data & behaviors. You can do so with any modern languages.
-So, instead of picking the System shape & filling the placeholders, you will create a new instance of the System type, providing name & description properties. Then attach a new instance of Container to this System, and so on. Plain-old coding.
-
-C4 model provides such API for both [.NET](https://github.com/structurizr/dotnet) & [Java](https://github.com/structurizr/java) languages.
-
-To ensure everyone can participate to model creation, a widespread practice is to shape a **D**omain **S**pecific **L**anguage. This particular language focuses only on a specific domain, hence the name. Narrowing the scope allows to end up with simple syntax and manageable rules, most of the people can rapidly learn & be proficient with. No more coding prerequisites. One well-known diagramming DSL is the [mermaid](https://mermaid-js.github.io/mermaid/#/) one.
-
-C4 model comes with its own, fully specified [here](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md).
-It defines types, data & structure as below:
-
-
-
-This simple grammar is easy to grasp, and layman friendly.
-Most often, DSL comes with syntax highlighter & analyzer as well to support user.
-DSL is also complemented with necessary tooling - more or less automated - that allows transformation of DSL into matching model structure.
-
-So whatever the entry point you pick, you now have a fully-described model you would like operate to surface compelling views.
-
-## Tags
-
-Tags is a very popular and powerful way to enrich a model. We often refer to this extra information as metadata. As you may have notice, the C4 model is quite simple. There is very few types (person, system, container, component). One can enrich the model by adding tags that will be used to:
-
-tailor the views (eg using a database shape for - guess what - stuff that are tagged with #database)
-filter the views (eg all component but those tagged with #external)
-...
-See tags as new dimensions you add to your model and you can leverage downstream to smartly shape the view(s).
-Unlike types, there is no constraints on tags, they are plain old text. That means you can tag the way you want, which can be good, but, corollary, you cannot leverage tooling to check for failure. Nothing will prevent you to misspell a word.
-
-## Views
-
-Uncoupling model from view(s) is the core concept of modern **UI** framework such as **M**odel **V**iew **V**iew**M**odel pattern.
-The underlying idea is to focus on creating a single rich model and be able to provide on-demand consolidated view(s).
-Applied to the solar system, we can end up with a model gathering planet name, traits (such as size, distance from the sun, ...), ...
-Then, we can expose and explore our model in many different ways like:
-
-
-
-
-## Theme
-
-By uncoupling model from view(s), we are now able to tailor view(s) without even touching the model.
-And theming is a very powerful tool to accommodate heterogenous users & situations.
-
-||||
-|-|-|-|
-|  | Semantic | C4 model semantic color schema we agree upon. |
-|  | Corporate | Need to incorporate diagramming within a slide deck or marketing materials where visual consistency does matter and sticks to corporate brand. Just swap your theme. |
-|  | High contrast | Experience should be tailored to every user. Every modern OS, IDE or application make accessibility a first-class citizen. Theming supports us on that field by enabling smart UX with a very limited investment. |
-
-## Point of views
-
-As said above, uncoupling model from view(s) allows to tailor as many views and as many forms we need to smartly explore our model.
-It is up to you to experience which shape you are more comfortable with, which one better conveys information, which one is better suited to support this kind of discussion or to interact with this particular audience.
-And the beauty here is that all of those are built upon a single common model. It is just different ways of interacting with this underlying model. Your model acts now as a database, you can query/filter/tailor to suit your needs.
-
-|||
-|-|-|
-| Exhaustive description of the ecosystem. |  |
-| Highlight workflow. |  |
-| Schematic view to gauge type & cardinality. |  |
-
-## Structurizr
-
-As an architecture as code evangelist, Simon Brown (creator of the C4 model) provides community with a comprehensive set of utility to shape & explore diagramming, the Structurizr suite:
-- [C4 DSL](https://github.com/structurizr/dsl): A way to create Structurizr software architecture models based upon the C4 model using a textual domain specific language
-- [C4 CLI](https://github.com/structurizr/cli): A command line utility for Structurizr, designed to be used in conjunction with the Structurizr DSL
-- [Structurizr](https://structurizr.com/): Visualize, document and explore your software architecture
-
-From here, we will leverage Structurizr suite to show case what one could expect from this model-first approach but keep in mind you should be able to end up with similar results using other alternatives.
-Moreover, Structurizr is smart enough to ship a docker-based lite version everyone can locally play with. Give it a try.
-
-Assuming your described your model leveraging the C4 DSL (200 lines of text for this particular sample), Structurizr crafts for you:
-
-|||
-|-|-|
-|  | Landscape aka C4.L |
-|  | Context aka C4.1 |
-|  | Container aka C4.2 |
-|  | Component aka C4.3 |
-|  | Back and forth navigation. |
-|  | All views can be dynamically filtered leveraging tags. Elements that does not fulfill tags query are made semi-transparent. |
-|  | You can craft filtered views from a single parent one to highlight different use cases. The layout is kept to ease comparison (spot the difference alike). |
-|  | As it can become difficult without speaker to support, complex diagram can be animated to support journey & ease understanding. |
-|  | Workflow aka C4.W. Relationships are indexed and animation can be played, including fading in/out elements to improve journey experience. |
-|  | Deployment aka C4.D. |
-|  | Real-time feedback. Diagram library is shaped & refined as you type. |
-|  | Every diagram comes with its own dynamic legend to underline active elements & their meaning. |
-|  | Graph view can be generated on-demand if you need to shift gears. |
-|  | Architecture Decision Record (see next chapter) support. |
-|  | Your markdown can embed dynamic & up to date C4 views you can interact with (not simple snapshots). |
-
-
-
-## Drawbacks
-
-|||
-|-|-|
-| Layout issue | One concern about **sketch-first** approach was Design Obsession ie grant to much time to sharp layout instead of improving the model. With **code-first** approach, we get rid of that which is most of the time fine, but there are still corner cases where auto-layout algorithm cannot do magic and you end up with a diagram which looks not optimal. Some tooling like Structurizr allows to switch to manual layout but it is not resilient to changes. Assuming those cases remain corner ones, you are safe. Otherwise, it is painful. |
-| Track to follow | Sometimes you may be tempted to enrich a diagram with some extras. If you leverage dedicated tooling, it is hard to do so as this tooling is there to constrain usage, and keep it compliant with the model and the convention. It is the price of auto-generation, there is no place for improvisation. Regarding the situation, it can be a good point or a bad one... |
-
-## Closing
-
-The code-first approach looks very interesting and straightforward, especially for people who are used to software development.
-Your software model is but yet another piece of code, obeying the same rules and processed through the same pipeline (source control, branching, Pull Request). As for deployment as code like Dockerfile that lands among C# files or python scripts, it seems very natural at the end to proceed this way.
-
-Dedicated tooling that morphs your model into meaningful views becomes part of the project CI/CD, and resulting materials full-blown project artifacts. It is then up to you to refine and improve the pipeline the way you are used to with source code. It may take time, but this time will probably be worth spent.
-
+---
+title: Architecture as code
+description: >
+ Deep dive code first approach, assets and drawbacks.
+weight: 6
+date: '2021-11-06'
+author: Romain Vasseur
+---
+
+Previously, we saw that **sketch-first** approach, as appealing as it may look like, comes with painful drawbacks that can prevent sizable project to properly scale eg huge maintenance cost, human error prone, ...
+
+This post will give some insights of the **code-first** or **architecture as code** approach, stressing out pros and cons of such a method.
+It should be read in parallel with [previous one](/docs/sketch), which covers the **architecture as sketch** or **sketch-first** approach.
+
+As always, **YMMV**, so spend time to learn and experience prior to make your **own** decision.
+
+## Recipe
+
+|||
+|-|-|
+| Describe | Leveraging either an API or a DSL, 1st stage is to describe your model in an human-readable, source control friendly way. |
+| Parse & build | Next stage is the realm of parser, analyzer & builder which are in charge of ingesting & validating model description and transforming it into a operable model. |
+| Explore | Final stage is to provide ways/views to explore and display your model to fit audience need and support discussion. |
+
+## Model
+
+Instead of drag & dropping shapes & arrows, code-first approach implies to write code. Amazing.
+A model can be defined as a set of types, data & behaviors. You can do so with any modern languages.
+So, instead of picking the System shape & filling the placeholders, you will create a new instance of the System type, providing name & description properties. Then attach a new instance of Container to this System, and so on. Plain-old coding.
+
+C4 model provides such API for both [.NET](https://github.com/structurizr/dotnet) & [Java](https://github.com/structurizr/java) languages.
+
+To ensure everyone can participate to model creation, a widespread practice is to shape a **D**omain **S**pecific **L**anguage. This particular language focuses only on a specific domain, hence the name. Narrowing the scope allows to end up with simple syntax and manageable rules, most of the people can rapidly learn & be proficient with. No more coding prerequisites. One well-known diagramming DSL is the [mermaid](https://mermaid-js.github.io/mermaid/#/) one.
+
+C4 model comes with its own, fully specified [here](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md).
+It defines types, data & structure as below:
+
+
+
+This simple grammar is easy to grasp, and layman friendly.
+Most often, DSL comes with syntax highlighter & analyzer as well to support user.
+DSL is also complemented with necessary tooling - more or less automated - that allows transformation of DSL into matching model structure.
+
+So whatever the entry point you pick, you now have a fully-described model you would like operate to surface compelling views.
+
+## Tags
+
+Tags is a very popular and powerful way to enrich a model. We often refer to this extra information as metadata. As you may have notice, the C4 model is quite simple. There is very few types (person, system, container, component). One can enrich the model by adding tags that will be used to:
+
+tailor the views (eg using a database shape for - guess what - stuff that are tagged with #database)
+filter the views (eg all component but those tagged with #external)
+...
+See tags as new dimensions you add to your model and you can leverage downstream to smartly shape the view(s).
+Unlike types, there is no constraints on tags, they are plain old text. That means you can tag the way you want, which can be good, but, corollary, you cannot leverage tooling to check for failure. Nothing will prevent you to misspell a word.
+
+## Views
+
+Uncoupling model from view(s) is the core concept of modern **UI** framework such as **M**odel **V**iew **V**iew**M**odel pattern.
+The underlying idea is to focus on creating a single rich model and be able to provide on-demand consolidated view(s).
+Applied to the solar system, we can end up with a model gathering planet name, traits (such as size, distance from the sun, ...), ...
+Then, we can expose and explore our model in many different ways like:
+
+
+
+
+## Theme
+
+By uncoupling model from view(s), we are now able to tailor view(s) without even touching the model.
+And theming is a very powerful tool to accommodate heterogenous users & situations.
+
+||||
+|-|-|-|
+|  | Semantic | C4 model semantic color schema we agree upon. |
+|  | Corporate | Need to incorporate diagramming within a slide deck or marketing materials where visual consistency does matter and sticks to corporate brand. Just swap your theme. |
+|  | High contrast | Experience should be tailored to every user. Every modern OS, IDE or application make accessibility a first-class citizen. Theming supports us on that field by enabling smart UX with a very limited investment. |
+
+## Point of views
+
+As said above, uncoupling model from view(s) allows to tailor as many views and as many forms we need to smartly explore our model.
+It is up to you to experience which shape you are more comfortable with, which one better conveys information, which one is better suited to support this kind of discussion or to interact with this particular audience.
+And the beauty here is that all of those are built upon a single common model. It is just different ways of interacting with this underlying model. Your model acts now as a database, you can query/filter/tailor to suit your needs.
+
+|||
+|-|-|
+| Exhaustive description of the ecosystem. |  |
+| Highlight workflow. |  |
+| Schematic view to gauge type & cardinality. |  |
+
+## Structurizr
+
+As an architecture as code evangelist, Simon Brown (creator of the C4 model) provides community with a comprehensive set of utility to shape & explore diagramming, the Structurizr suite:
+- [C4 DSL](https://github.com/structurizr/dsl): A way to create Structurizr software architecture models based upon the C4 model using a textual domain specific language
+- [C4 CLI](https://github.com/structurizr/cli): A command line utility for Structurizr, designed to be used in conjunction with the Structurizr DSL
+- [Structurizr](https://structurizr.com/): Visualize, document and explore your software architecture
+
+From here, we will leverage Structurizr suite to show case what one could expect from this model-first approach but keep in mind you should be able to end up with similar results using other alternatives.
+Moreover, Structurizr is smart enough to ship a docker-based lite version everyone can locally play with. Give it a try.
+
+Assuming your described your model leveraging the C4 DSL (200 lines of text for this particular sample), Structurizr crafts for you:
+
+|||
+|-|-|
+|  | Landscape aka C4.L |
+|  | Context aka C4.1 |
+|  | Container aka C4.2 |
+|  | Component aka C4.3 |
+|  | Back and forth navigation. |
+|  | All views can be dynamically filtered leveraging tags. Elements that does not fulfill tags query are made semi-transparent. |
+|  | You can craft filtered views from a single parent one to highlight different use cases. The layout is kept to ease comparison (spot the difference alike). |
+|  | As it can become difficult without speaker to support, complex diagram can be animated to support journey & ease understanding. |
+|  | Workflow aka C4.W. Relationships are indexed and animation can be played, including fading in/out elements to improve journey experience. |
+|  | Deployment aka C4.D. |
+|  | Real-time feedback. Diagram library is shaped & refined as you type. |
+|  | Every diagram comes with its own dynamic legend to underline active elements & their meaning. |
+|  | Graph view can be generated on-demand if you need to shift gears. |
+|  | Architecture Decision Record (see next chapter) support. |
+|  | Your markdown can embed dynamic & up to date C4 views you can interact with (not simple snapshots). |
+
+
+
+## Drawbacks
+
+|||
+|-|-|
+| Layout issue | One concern about **sketch-first** approach was Design Obsession ie grant to much time to sharp layout instead of improving the model. With **code-first** approach, we get rid of that which is most of the time fine, but there are still corner cases where auto-layout algorithm cannot do magic and you end up with a diagram which looks not optimal. Some tooling like Structurizr allows to switch to manual layout but it is not resilient to changes. Assuming those cases remain corner ones, you are safe. Otherwise, it is painful. |
+| Track to follow | Sometimes you may be tempted to enrich a diagram with some extras. If you leverage dedicated tooling, it is hard to do so as this tooling is there to constrain usage, and keep it compliant with the model and the convention. It is the price of auto-generation, there is no place for improvisation. Regarding the situation, it can be a good point or a bad one... |
+
+## Closing
+
+The code-first approach looks very interesting and straightforward, especially for people who are used to software development.
+Your software model is but yet another piece of code, obeying the same rules and processed through the same pipeline (source control, branching, Pull Request). As for deployment as code like Dockerfile that lands among C# files or python scripts, it seems very natural at the end to proceed this way.
+
+Dedicated tooling that morphs your model into meaningful views becomes part of the project CI/CD, and resulting materials full-blown project artifacts. It is then up to you to refine and improve the pipeline the way you are used to with source code. It may take time, but this time will probably be worth spent.
+
As stressed before, code-first & sketch-first approaches are the 2 ends of the spectrum. You may end up with mixing them together, or shaping an in-between one. Choice is yours to pick but remember that there is no single approach to fit them all, and best decisions are contextual ones.
\ No newline at end of file
diff --git a/docs/content/docs/convention.md b/docs/content/docs/convention.md
index a344a49..9748ced 100644
--- a/docs/content/docs/convention.md
+++ b/docs/content/docs/convention.md
@@ -1,106 +1,106 @@
----
-title: Convention
-description: >
- Define and agree upon conventions to enforce model consistency.
-weight: 3
-date: '2021-11-03'
-author: Romain Vasseur
----
-
-Main challenge of diagramming is to convey multi-dimensional message to heterogeneous audience. Find below some conventions, one could leverage to empower the vision he would like to convey while minimizing mental workload.
-
-## Self-contained
-
-There are some aspects that are not straightforward to achieve when speaking about diagramming. A famous one, common to all documentation materials, is the ability to keep content up to date. Another core one is the ability for a content to be effectively processed without support of a speaker or 100 pages manual. One diagram should clearly expose aspect(s) of an architecture in an autonomous fashion.
-Let's list below some points you should pay attention at to achieve this
-
-### Taxonomy
-
-Properly name thing is an important part of every design. Because one could never foresee knowledge and skills of the audience, one should prevent himself to leverage acronyms and prefer meaningful word to name the things.
-
-Remember that your diagramming has to be self-explanatory without the need of a speaker to explain every ambiguous wording that may pop-up.
-
-For example, on one hand, some are used to use RT for Real Time. On another hand, others are used to use RT for Ray Tracing. You can easily grab how cumbersome situation will become, if one need to sketch application that mixes those 2 contexts and decide to stick to acronyms.
-
-Take the habit to explicitly name stuff. And feel free to come with unique name. Especially when you need to couple with others that have same wording for different meaning. One more time, ubiquitous language is the way to go.
-
-### Type | Tech | Payload
-
-Once naming stage is over, it is time to give more insights. Important traits to consider are:
-
-|||
-|-|-|
-| Type| Main category e.g. `software system`, `container`, `component`. It could be complemented by semantic color schema to speed up visual segmentation. |
-| Technology | Underlying technology. This one is refined along with zooming in. Pay attention to provide information accurate to the level you are in. When dealing with container level, it is perfectly fine to have a `Single Page Application` specifying `Blazor WASM` as underlying technology stack. Most of the time, it is not useful at this stage to provide neither language information nor version of it. Same goes to enrich relationship through boxes through arrows. At a `software system` level, it could be fine to only surface technology agnostic interaction to stress the coupling. When you dive in, you can then refine information by specifying `REST` or `gRPC`. |
-| Payload | As exchanges are an important part of an application, you should provide meaningful information. It is the perfect place to highlight that you use some data standard or detail payload specificity. Prefer one-way arrows if relationship is not symmetric as it is easier to reason about, especially when you describe workflows. |
-
-### Description
-
-Last stage is to provide meaningful description to crystallize purpose & behavior. Information must be contextually tailored as you want your audience to quickly grasp it.
-Pay attention to not repeat yourself (DRY pattern applies to diagramming as well). Name & type are already defined above, so spare your words and starts your sentence with a verb. It will be straightforward for the reader to assemble all parts by prefixing description by type-name tuple.
-
-## Visual consistency
-
-When we talk about classification, regardless of the pattern, we relatively quickly hit the point of making a decision regarding cardinality. It is pretty much like lasagna where most of the chefs have an opinion about the ideal number of layers one should stack to cook the best dish...
-There is no universal answer - and for sure it is not 42 - and YMMV but a good guideline could be:
-- Do take enough to achieve goal
-- Don't take too much to avoid endless discussion about neighborhood dispute...
-
-### Color
-
-Color is a powerful vector to visually identify and cluster stuff. Eg, we are used to pick green for forest and blue for sea when we color a map, whatever our culture, our country, ...
-Same should apply for diagramming. Color should be used to support semantic. Sticking to C4 model, one could end up with the following schema.
-
-||||
-|-|-|-|
-| Persona | Purple | Color of royalty.
Because end-user/customer is the only one to please at the very end |
-| System | Blue | Color of ocean.
Systems are big blobs that arise, shape & evolve within a bigger ecosystem. |
-| Container | Red | Color of danger.
The place where you make important split decision in terms of unit of deployment for your application. |
-| Component | Green | Color of sustainability.
Whatever the shape of the final application your components will be part of, they are there to last. |
-| Out of scope | Gray | Color of shadow/half-light.
Support schema by complementing with context without noising the primary intent. |
-| Code | | Because the last stage deep dives in specific implementation, there is no enforced policy there. This said, it is recommended to define local semantic as well eg hexagonal layers color mapping. |
-
-### Shape
-
-Shape is another well-known and broadly used tool to discriminate stuff and ease classification. To achieve this goal, shapes should be meaningful and usage broadly acknowledged.
-
-
-
-### Transparency
-
-Transparency is often used to highlight required content from optional one. It is recommended to stick to 3 visibility states as it could be difficult especially when materials are broadcasted and recorded to visually discriminate between many levels of transparency:
-
-- Visible: component is required
-- Transparent: component is optional
-- Not visible: component does not bring any value for this contextual view.
-
-### Style
-
-Streamlining style is an important part prior to ship anything. Uncluttered eye-candy layout conveys subliminal positive information to end-user. If your diagramming looks good and easy to grasp, you install confidence. Otherwise, it may indicate that underlying implementation is so poor that you are not able to surface a clear and understandable view of it.
-
-Define and enforce usage of architecture style over ones that do not enforce semantic or are likely to change without adding any value like brand color palette.
-
-Amend core rules only if you think it brings value for reader. For example, if you have 2 concurrent workflows you would like to prompt on the same diagram, pick a color for each of them.
-
-### Layer
-
-Layers are highly efficient tooling to cluster information. Unsurprisingly, they come in handy for diagramming as well. Remember that most of the systems you will interact with, even the simplest ones, are inherently multi-dimensional.
-
-Segmenting the information will allow you to contextually tailor views and provide on-demand schema. It is important to enrich your model with all meaningful metadata. This said, it is not especially helpful to end up with views that mix & match orthogonal traits. Too many stuff had nothing but noise. Shaping a single view that can accommodate every audience and context is a pipe dream. If you don't need content, don't show it. It is simple as it sounds and will prevent speaker to lose 5 minutes explaining what to focus on and what to omit every time the diagram is used to support a discussion.
-
-Sadly, there are a lot of poorly materials living around that stick to this anti-pattern...
-
-### Icon
-
-Complementing a model with metadata is a good habit to tailor contextual views, but can rapidly become cumbersome and noise the whole picture. Naming length can also blur the picture.
-As we previously said that using acronyms is generally a bad habit (of course, when there is no ambiguity, they are fine e.g. gRPC, REST, CRUD, ...), we need to find another way to shorten information without losing accuracy.
-
-One well-known tool for that are icons. There are tiny, eye-candy, most of the time self-explanatory and culture neutral. And last but not least are easily processed by human being. No more reading, welcome to visual memory.
-
-If you decide to opt for icon usage, please enforce coherency by leveraging icon library (tere are many free available) instead of random google harvest, as it will defeat the initial purpose.
-
-## Closing
-
-So, we go over some useful conventions one should enforce in his model to ensure he surfaces consolidated & compelling materials.
-It is now time to see how we can apply all we have learned so far.
+---
+title: Convention
+description: >
+ Define and agree upon conventions to enforce model consistency.
+weight: 3
+date: '2021-11-03'
+author: Romain Vasseur
+---
+
+Main challenge of diagramming is to convey multi-dimensional message to heterogeneous audience. Find below some conventions, one could leverage to empower the vision he would like to convey while minimizing mental workload.
+
+## Self-contained
+
+There are some aspects that are not straightforward to achieve when speaking about diagramming. A famous one, common to all documentation materials, is the ability to keep content up to date. Another core one is the ability for a content to be effectively processed without support of a speaker or 100 pages manual. One diagram should clearly expose aspect(s) of an architecture in an autonomous fashion.
+Let's list below some points you should pay attention at to achieve this
+
+### Taxonomy
+
+Properly name thing is an important part of every design. Because one could never foresee knowledge and skills of the audience, one should prevent himself to leverage acronyms and prefer meaningful word to name the things.
+
+Remember that your diagramming has to be self-explanatory without the need of a speaker to explain every ambiguous wording that may pop-up.
+
+For example, on one hand, some are used to use RT for Real Time. On another hand, others are used to use RT for Ray Tracing. You can easily grab how cumbersome situation will become, if one need to sketch application that mixes those 2 contexts and decide to stick to acronyms.
+
+Take the habit to explicitly name stuff. And feel free to come with unique name. Especially when you need to couple with others that have same wording for different meaning. One more time, ubiquitous language is the way to go.
+
+### Type | Tech | Payload
+
+Once naming stage is over, it is time to give more insights. Important traits to consider are:
+
+|||
+|-|-|
+| Type| Main category e.g. `software system`, `container`, `component`. It could be complemented by semantic color schema to speed up visual segmentation. |
+| Technology | Underlying technology. This one is refined along with zooming in. Pay attention to provide information accurate to the level you are in. When dealing with container level, it is perfectly fine to have a `Single Page Application` specifying `Blazor WASM` as underlying technology stack. Most of the time, it is not useful at this stage to provide neither language information nor version of it. Same goes to enrich relationship through boxes through arrows. At a `software system` level, it could be fine to only surface technology agnostic interaction to stress the coupling. When you dive in, you can then refine information by specifying `REST` or `gRPC`. |
+| Payload | As exchanges are an important part of an application, you should provide meaningful information. It is the perfect place to highlight that you use some data standard or detail payload specificity. Prefer one-way arrows if relationship is not symmetric as it is easier to reason about, especially when you describe workflows. |
+
+### Description
+
+Last stage is to provide meaningful description to crystallize purpose & behavior. Information must be contextually tailored as you want your audience to quickly grasp it.
+Pay attention to not repeat yourself (DRY pattern applies to diagramming as well). Name & type are already defined above, so spare your words and starts your sentence with a verb. It will be straightforward for the reader to assemble all parts by prefixing description by type-name tuple.
+
+## Visual consistency
+
+When we talk about classification, regardless of the pattern, we relatively quickly hit the point of making a decision regarding cardinality. It is pretty much like lasagna where most of the chefs have an opinion about the ideal number of layers one should stack to cook the best dish...
+There is no universal answer - and for sure it is not 42 - and YMMV but a good guideline could be:
+- Do take enough to achieve goal
+- Don't take too much to avoid endless discussion about neighborhood dispute...
+
+### Color
+
+Color is a powerful vector to visually identify and cluster stuff. Eg, we are used to pick green for forest and blue for sea when we color a map, whatever our culture, our country, ...
+Same should apply for diagramming. Color should be used to support semantic. Sticking to C4 model, one could end up with the following schema.
+
+||||
+|-|-|-|
+| Persona | Purple | Color of royalty.
Because end-user/customer is the only one to please at the very end |
+| System | Blue | Color of ocean.
Systems are big blobs that arise, shape & evolve within a bigger ecosystem. |
+| Container | Red | Color of danger.
The place where you make important split decision in terms of unit of deployment for your application. |
+| Component | Green | Color of sustainability.
Whatever the shape of the final application your components will be part of, they are there to last. |
+| Out of scope | Gray | Color of shadow/half-light.
Support schema by complementing with context without noising the primary intent. |
+| Code | | Because the last stage deep dives in specific implementation, there is no enforced policy there. This said, it is recommended to define local semantic as well eg hexagonal layers color mapping. |
+
+### Shape
+
+Shape is another well-known and broadly used tool to discriminate stuff and ease classification. To achieve this goal, shapes should be meaningful and usage broadly acknowledged.
+
+
+
+### Transparency
+
+Transparency is often used to highlight required content from optional one. It is recommended to stick to 3 visibility states as it could be difficult especially when materials are broadcasted and recorded to visually discriminate between many levels of transparency:
+
+- Visible: component is required
+- Transparent: component is optional
+- Not visible: component does not bring any value for this contextual view.
+
+### Style
+
+Streamlining style is an important part prior to ship anything. Uncluttered eye-candy layout conveys subliminal positive information to end-user. If your diagramming looks good and easy to grasp, you install confidence. Otherwise, it may indicate that underlying implementation is so poor that you are not able to surface a clear and understandable view of it.
+
+Define and enforce usage of architecture style over ones that do not enforce semantic or are likely to change without adding any value like brand color palette.
+
+Amend core rules only if you think it brings value for reader. For example, if you have 2 concurrent workflows you would like to prompt on the same diagram, pick a color for each of them.
+
+### Layer
+
+Layers are highly efficient tooling to cluster information. Unsurprisingly, they come in handy for diagramming as well. Remember that most of the systems you will interact with, even the simplest ones, are inherently multi-dimensional.
+
+Segmenting the information will allow you to contextually tailor views and provide on-demand schema. It is important to enrich your model with all meaningful metadata. This said, it is not especially helpful to end up with views that mix & match orthogonal traits. Too many stuff had nothing but noise. Shaping a single view that can accommodate every audience and context is a pipe dream. If you don't need content, don't show it. It is simple as it sounds and will prevent speaker to lose 5 minutes explaining what to focus on and what to omit every time the diagram is used to support a discussion.
+
+Sadly, there are a lot of poorly materials living around that stick to this anti-pattern...
+
+### Icon
+
+Complementing a model with metadata is a good habit to tailor contextual views, but can rapidly become cumbersome and noise the whole picture. Naming length can also blur the picture.
+As we previously said that using acronyms is generally a bad habit (of course, when there is no ambiguity, they are fine e.g. gRPC, REST, CRUD, ...), we need to find another way to shorten information without losing accuracy.
+
+One well-known tool for that are icons. There are tiny, eye-candy, most of the time self-explanatory and culture neutral. And last but not least are easily processed by human being. No more reading, welcome to visual memory.
+
+If you decide to opt for icon usage, please enforce coherency by leveraging icon library (tere are many free available) instead of random google harvest, as it will defeat the initial purpose.
+
+## Closing
+
+So, we go over some useful conventions one should enforce in his model to ensure he surfaces consolidated & compelling materials.
+It is now time to see how we can apply all we have learned so far.
Next [session](/docs/mila) will process a fictional case study, explaining step by step decisions that have been made to craft the different diagrams.
\ No newline at end of file
diff --git a/docs/content/docs/mila.md b/docs/content/docs/mila.md
index 7de10f2..1bb8062 100644
--- a/docs/content/docs/mila.md
+++ b/docs/content/docs/mila.md
@@ -1,56 +1,56 @@
----
-title: MILA case study
-description: >
- End-to-end simple case study.
-weight: 4
-date: '2021-11-04'
-author: Romain Vasseur
----
-
-For this session we will use an hypothetical use case, namely __Turning one or multiple pictures into a rendering material for Labyrinth__, to see how one could potentially craft the implementation sticking to `C4 model`. Codename of the project is `MILA` standing for `Multiple Images Lightweight Acquisition`. Let's unfold the 4 stages and analyze what you should pay attention to, to tailor the best experience for your audience.
-
-## C4.1 Context
-
-Highest zoom level where you show where your system lives.
-
-
-
-One should be able to easily grasp interactions with both user(s) & external system(s), if any.
-- `MILA` is the `software system` we are focusing on. We provide a high level description enabling a layman to quickly jump in.
-- A single identified `Persona`. As their title - material scientist - highlights, we are talking about a seasoned user. We capture in the description how they will interact with our application.
-- We materialize coupling with external `software system`, here `Icarus`. You may notice that we do not provide neither generic description nor exhaustive listing of facilities. We pick those which are contextually meaningful.
-- We use one-way technology agnostic arrows for `relationships` with straightforward intent. Prefer plain old English sentence starting with a verb. One can then fluently read the diagram, prefixing & suffixing the sentence accordingly e.g. `Material scientist` sends pictures to `MILA` or `Icarus` fetches materials from `MILA`. At this stage, it seems useless to give more insights especially regarding technology stack.
-
-## C4.2 Container
-
-Coming from the `Context` diagram, imagine you zoomed in on the `MILA` blue box.
-
-
-
-A system is composed by container(s) - think executable granularity such as desktop app, web app, backend, database...
-- A dashed bounding box stresses parent `software system` boundary.
-- Involved `person` & external `software system` are still presents and help us to refine which internal parts are coupled. One could notice that `API` application is totally agnostic of `MILA` system I/O.
-- Two entry points with asymmetric facilities & different form factors to interact with our application from an end-user perspective...
-- … both leveraging - through gRPC - a back-end service for post-processing...
-- … which in turn persists enriched data into some storage area.
-- Starting from container cardinality & heterogeneity, we are able to sketch how one could deploy the application, organize both source code control & backlog, and tailor team(s) accordingly.
-
-## C4.3 Component
-
-Coming from the `Container` diagram, imagine you jumped in the `Mobile` application red box.
-
-
-
-`Component` stage is the place where we split a given `container` into bounding contexts. This stage is very important as component should be crafted in a sustainable way. Take the opportunity to see beyond the current use case and put genericity & agnosticity as first-class citizen. As for Lego or Tangram, pieces should be reused in a near future for a brand-new application.
-- A dashed bounding box stresses parent `container` boundary.
-- Notice how we specify `language` for each of the components.
-- We clearly materialize `relationships` as well
-- And as always, ensure you provide proper naming & description.
-
-## C4.4 Code
-
-One last time, coming from the `Component` diagram, imagine you stepped into the `Uploading` green box.
-
-
-
+---
+title: MILA case study
+description: >
+ End-to-end simple case study.
+weight: 4
+date: '2021-11-04'
+author: Romain Vasseur
+---
+
+For this session we will use an hypothetical use case, namely __Turning one or multiple pictures into a rendering material for Labyrinth__, to see how one could potentially craft the implementation sticking to `C4 model`. Codename of the project is `MILA` standing for `Multiple Images Lightweight Acquisition`. Let's unfold the 4 stages and analyze what you should pay attention to, to tailor the best experience for your audience.
+
+## C4.1 Context
+
+Highest zoom level where you show where your system lives.
+
+
+
+One should be able to easily grasp interactions with both user(s) & external system(s), if any.
+- `MILA` is the `software system` we are focusing on. We provide a high level description enabling a layman to quickly jump in.
+- A single identified `Persona`. As their title - material scientist - highlights, we are talking about a seasoned user. We capture in the description how they will interact with our application.
+- We materialize coupling with external `software system`, here `Icarus`. You may notice that we do not provide neither generic description nor exhaustive listing of facilities. We pick those which are contextually meaningful.
+- We use one-way technology agnostic arrows for `relationships` with straightforward intent. Prefer plain old English sentence starting with a verb. One can then fluently read the diagram, prefixing & suffixing the sentence accordingly e.g. `Material scientist` sends pictures to `MILA` or `Icarus` fetches materials from `MILA`. At this stage, it seems useless to give more insights especially regarding technology stack.
+
+## C4.2 Container
+
+Coming from the `Context` diagram, imagine you zoomed in on the `MILA` blue box.
+
+
+
+A system is composed by container(s) - think executable granularity such as desktop app, web app, backend, database...
+- A dashed bounding box stresses parent `software system` boundary.
+- Involved `person` & external `software system` are still presents and help us to refine which internal parts are coupled. One could notice that `API` application is totally agnostic of `MILA` system I/O.
+- Two entry points with asymmetric facilities & different form factors to interact with our application from an end-user perspective...
+- … both leveraging - through gRPC - a back-end service for post-processing...
+- … which in turn persists enriched data into some storage area.
+- Starting from container cardinality & heterogeneity, we are able to sketch how one could deploy the application, organize both source code control & backlog, and tailor team(s) accordingly.
+
+## C4.3 Component
+
+Coming from the `Container` diagram, imagine you jumped in the `Mobile` application red box.
+
+
+
+`Component` stage is the place where we split a given `container` into bounding contexts. This stage is very important as component should be crafted in a sustainable way. Take the opportunity to see beyond the current use case and put genericity & agnosticity as first-class citizen. As for Lego or Tangram, pieces should be reused in a near future for a brand-new application.
+- A dashed bounding box stresses parent `container` boundary.
+- Notice how we specify `language` for each of the components.
+- We clearly materialize `relationships` as well
+- And as always, ensure you provide proper naming & description.
+
+## C4.4 Code
+
+One last time, coming from the `Component` diagram, imagine you stepped into the `Uploading` green box.
+
+
+
At this low-level stage, we need to refine the way we will craft the bounding context we are focusing at. A good way to shape modern application is to stick to `hexagonal` (onion, port & adapter, & Co siblings) architecture. It is then very easy to highlight the different projects involved, including the layer they belong to. It is now time to really detail the technical stack. Pay attention to the way you name your project, and of course provide meaningful descriptions to sum up responsibility of each projects
\ No newline at end of file
diff --git a/docs/content/docs/project-lifecycle.md b/docs/content/docs/project-lifecycle.md
index 83d4bfe..3f28f14 100644
--- a/docs/content/docs/project-lifecycle.md
+++ b/docs/content/docs/project-lifecycle.md
@@ -1,104 +1,104 @@
----
-title: Project lifecycle
-description: >
- Map C4 model approach into daily life.
-weight: 7
-date: '2021-11-07'
-author: Romain Vasseur
----
-
-Here we are. We spent time to craft a software model, to agree upon convention and to exercise different approaches, namely sketch-first & code-first approaches. It is great. But at the end of the day comes the question: how can one leverage all of this in his daily life? As we said before, we do not invest time and energy for fun. We want our cash back.
-
-Remember, we can surface our underlying model in many different flavors. Leveraging the schematic and tightened tile-based view will be perfect to support the discussion today. Remember what we have in stock:
-
-C4 main stages: Context, Container, Component & Code.
-
-
-
-C4 complementary stages: Landscape, Workflow & Deployment.
-
-
-
-Starting from this, see how one could effectively achieve different missions within a project.
-
-## I need to shape a solution
-
-I am likely to be - or acting as - a **solution architect** or a **product manager**. My goal is to quickly grasp how the ecosystem look like, how I can couple with existing products, how I can shape a new solution, morph an existing one, ... To do so, I can navigate back and forth between **C4.L** & **C4.1**, stressing out synergies & coupling, and start to sketch the future.
-
-
-
-{{% alert color="warning" %}}
-Capture the ecosystem and shape portfolio.
-{{% /alert %}}
-
-## I need to tailor a solution
-
-I am likely to be - or acting as - a **product owner** or **UX designer**. I would like to express how end-users will interact with my products, and refining key workflows. I can do so using **C4.1**, **C4.2** & **C4.W**, which let me focus on both static & dynamic aspects of the usage. I can gauge what should make sense in term of form-factor, and how stuff snaps into place.
-
-
-
-{{% alert color="warning" %}}
-Streamline user experience and stress out key features.
-{{% /alert %}}
-
-## I need to size a solution
-
-I am likely to be - or acting as - a **project manager** or a **team member**. I am in charge of providing consolidated metrics to plan a development. I can incrementally refine figures following up **C4** stages split.
-
-
-
-{{% alert color="warning" %}}
-Improving sizing while decreasing risk.
-{{% /alert %}}
-
-One word about work quantification activity, often (poorly) referred as sizing activity. Work quantification is an incremental activity. To better materialize the stages - and their underlying implication - it is more accurate to speak about bet, estimate & sizing instead of a single sizing one.
-
-## I need to develop a solution
-
-I am likely to be - or acting as - an **architect**, a **technical lead** or a **team member**. The comprehensive set of **C4** main stages are perfect to feed my backlog, support the development and introduce my demos. Main workflows are properly materialized using **C4.W** and support discussion such as performance or payload format.
-
-
-
-{{% alert color="warning" %}}
-Pave the path and support technical decision making.
-{{% /alert %}}
-
-## I need to deploy a solution
-
-I am likely to be - or acting as - a **devops**. **C4.1** and **C4.2** outline the big picture, when **C4.D** materializes how things will come in term of unit of deployment. I can leverage **C4.W** to ensure deployment will take into account workflows to optimize for data locality or smart clustering.
-
-
-
-{{% alert color="warning" %}}
-Tailor deployment.
-{{% /alert %}}
-
-## I need to document a solution
-
-I am likely to be - or acting as - a **technical writer** or a **team member**. I can focus on **C4.1** & **C4.2** to set the scene. Then, all the **C4.W** are perfect material to ensure documentation will cover all main use cases, and usher end-user through his usage.
-
-
-
-{{% alert color="warning" %}}
-Pen compelling documentation.
-{{% /alert %}}
-
-## I need to market a solution
-
-I am likely to be - or acting as - a **pre-sales** or **application engineer**. I would like to leverage all the existing **C4** materials, but emphasize brand consistency. I focus on feeding my audience with straightforward view of what should be done, and how things are linked and distributed. My work can be part of broader one which dictates its own rule regarding style.
-
-
-
-{{% alert color="warning" %}}
-Brand technical proposal.
-{{% /alert %}}
-
-## I need to...
-
-It is up to you, **fellow readers**, to fill the dot.
-Up to you to unleash the power of your software model to successfully craft and deliver the solution you are part of.
-Journey is far to be over. It is just the beginning. And your have been cast to play at the forefront!!
-
-{{% alert color="warning" %}}
-Experience. Improve. Share. Enjoy.
+---
+title: Project lifecycle
+description: >
+ Map C4 model approach into daily life.
+weight: 7
+date: '2021-11-07'
+author: Romain Vasseur
+---
+
+Here we are. We spent time to craft a software model, to agree upon convention and to exercise different approaches, namely sketch-first & code-first approaches. It is great. But at the end of the day comes the question: how can one leverage all of this in his daily life? As we said before, we do not invest time and energy for fun. We want our cash back.
+
+Remember, we can surface our underlying model in many different flavors. Leveraging the schematic and tightened tile-based view will be perfect to support the discussion today. Remember what we have in stock:
+
+C4 main stages: Context, Container, Component & Code.
+
+
+
+C4 complementary stages: Landscape, Workflow & Deployment.
+
+
+
+Starting from this, see how one could effectively achieve different missions within a project.
+
+## I need to shape a solution
+
+I am likely to be - or acting as - a **solution architect** or a **product manager**. My goal is to quickly grasp how the ecosystem look like, how I can couple with existing products, how I can shape a new solution, morph an existing one, ... To do so, I can navigate back and forth between **C4.L** & **C4.1**, stressing out synergies & coupling, and start to sketch the future.
+
+
+
+{{% alert color="warning" %}}
+Capture the ecosystem and shape portfolio.
+{{% /alert %}}
+
+## I need to tailor a solution
+
+I am likely to be - or acting as - a **product owner** or **UX designer**. I would like to express how end-users will interact with my products, and refining key workflows. I can do so using **C4.1**, **C4.2** & **C4.W**, which let me focus on both static & dynamic aspects of the usage. I can gauge what should make sense in term of form-factor, and how stuff snaps into place.
+
+
+
+{{% alert color="warning" %}}
+Streamline user experience and stress out key features.
+{{% /alert %}}
+
+## I need to size a solution
+
+I am likely to be - or acting as - a **project manager** or a **team member**. I am in charge of providing consolidated metrics to plan a development. I can incrementally refine figures following up **C4** stages split.
+
+
+
+{{% alert color="warning" %}}
+Improving sizing while decreasing risk.
+{{% /alert %}}
+
+One word about work quantification activity, often (poorly) referred as sizing activity. Work quantification is an incremental activity. To better materialize the stages - and their underlying implication - it is more accurate to speak about bet, estimate & sizing instead of a single sizing one.
+
+## I need to develop a solution
+
+I am likely to be - or acting as - an **architect**, a **technical lead** or a **team member**. The comprehensive set of **C4** main stages are perfect to feed my backlog, support the development and introduce my demos. Main workflows are properly materialized using **C4.W** and support discussion such as performance or payload format.
+
+
+
+{{% alert color="warning" %}}
+Pave the path and support technical decision making.
+{{% /alert %}}
+
+## I need to deploy a solution
+
+I am likely to be - or acting as - a **devops**. **C4.1** and **C4.2** outline the big picture, when **C4.D** materializes how things will come in term of unit of deployment. I can leverage **C4.W** to ensure deployment will take into account workflows to optimize for data locality or smart clustering.
+
+
+
+{{% alert color="warning" %}}
+Tailor deployment.
+{{% /alert %}}
+
+## I need to document a solution
+
+I am likely to be - or acting as - a **technical writer** or a **team member**. I can focus on **C4.1** & **C4.2** to set the scene. Then, all the **C4.W** are perfect material to ensure documentation will cover all main use cases, and usher end-user through his usage.
+
+
+
+{{% alert color="warning" %}}
+Pen compelling documentation.
+{{% /alert %}}
+
+## I need to market a solution
+
+I am likely to be - or acting as - a **pre-sales** or **application engineer**. I would like to leverage all the existing **C4** materials, but emphasize brand consistency. I focus on feeding my audience with straightforward view of what should be done, and how things are linked and distributed. My work can be part of broader one which dictates its own rule regarding style.
+
+
+
+{{% alert color="warning" %}}
+Brand technical proposal.
+{{% /alert %}}
+
+## I need to...
+
+It is up to you, **fellow readers**, to fill the dot.
+Up to you to unleash the power of your software model to successfully craft and deliver the solution you are part of.
+Journey is far to be over. It is just the beginning. And your have been cast to play at the forefront!!
+
+{{% alert color="warning" %}}
+Experience. Improve. Share. Enjoy.
{{% /alert %}}
\ No newline at end of file
diff --git a/docs/content/docs/sketch.md b/docs/content/docs/sketch.md
index 7f5eac7..6302d50 100644
--- a/docs/content/docs/sketch.md
+++ b/docs/content/docs/sketch.md
@@ -1,102 +1,102 @@
----
-title: Architecture as sketch
-description: >
- Deep dive sketch first approach, assets and drawbacks.
-weight: 5
-date: '2021-11-05'
-author: Romain Vasseur
----
-
-We are used to **xxx as code** (deployment as code, architecture as code) stuff or **xxx-first** (view-first, view-model-first) approaches to specify from which end we start a journey or we tackle an issue. It is a very important step as it contrasts how we address a situation, especially the inherent biases we should be aware of and keep under control.
-
-This post will give some insights of the **sketch-first** or **architecture as sketch** approach, stressing out pros and cons of such a method.
-It should be read in parallel with [next one](/docs/code), which will cover the **architecture as code** or **code-first** approach.
-
-Of course, those are the 2 ends of the spectrum. You may end up with mixing the 2 approaches, or shaping an in-between one.
-Choice is yours to pick but remember to make **contextual** decision.
-There is no per say bad choices, provided that you can explain why you made it.
-Thus, the importance of tracking those choices to be able to rewind & replay without be tempting to rewrite the history.
-Luckily, we will cover this topic a bit later in the `Architecture Decision Record` stage.
-
-## Whiteboard
-
-First thing you may have heard about properly touching upon development is to start with a design phase. To stress that point, some advertise to stay away from any form of IDE or computer. Here came the golden age of whiteboarding. A couple of markers and basic drawing skills empower anyone to tailor unmatched diagrams. But nothing is that simple.
-
-Before talking about what are inherent limitations of this approach, let's start with its valuable benefits.
-
-|||
-|-|-|
-| Low prerequisites...| Nothing but a room & a couple of markers to engage... |
-| Quick start-up | Meet & sketch. Straightforward. At least, seems to be... |
-| Team friendly | Gathering in a single place, as a team, focusing all together on a dedicated problem, fosters creativity. |
-
-But reality is rapidly catching up...
-
-What we imagine ending up with...
-
-
-
-... and what we are likely to inherit...
-
-
-
-Very few of us that previously experienced this whiteboard-based design approach can shamelessly say that:
-- They never take a snapshot of a whiteboard for later (and drop it within a pompous MoM email...)
-- They never annotate a cryptic whiteboard with an equally cryptic do not erase (please) for posterity
-- They never entirely rewrite the same sketch multiple times (and often in the same brainstorming session)
-- ...
-
-This first step is very valuable to gauge what we should end up with, and maybe more important what we should avoid ending up with. Despite its apparent simplicity, it appears that crafting valuable materials is not that straightforward, and a bunch of unexpected issues arise...
-
-|||
-|-|-|
-| Lack of sustainability | First move could be a cheap one. But you are doomed to pay penalty for any consecutive ones. Assuming you managed to draft a meaningful diagram, you are stuck with persistence, upcoming checkout and modifications, version tracking, ... |
-| No resilience to changes | Design are inherently incremental and poorly accommodates with whiteboarding. Eg there is no simple way to make room for new piece in an existing sketch. CrUD and layout operations are very costly, as they mostly imply a complete redraw. |
-| Not at all eye-candy | It is difficult but not impossible to sketch nice stuff (but it implies some drawing skills that are not those common). But it is quite impossible to achieve at the first trial, especially when we start from blank page. Whatever the time you spent, you will end up somewhere between a mess & a draft. Do not expect more. |
-
-What is wrong? We started whiteboarding - aka collaborative pen & paper - following the initial advice prescribing to stay away from any form of IDE or computer. At least, that's what we thought. This guideline is not the original one but a poor translation aimed at beginners. And, as often when smart guys try to popularize, misleading.
-**Prevent yourself to code before designing** is the mantra we should stick to.
-Of course, if you do not access neither an IDE nor a computer, you won't be able to code, but is is merely a side-effect...
-
-We all are engineers. Engineers cope with issues with methods and tools.
-We define method 2 chapters ago, spending time to introduce [C4 model](/docs/c4-model) & [convention](/docs/convention).
-It is now time to tailor tools. And software engineers tools are - guess what - software...
-
-## Diagramming software
-
-Whatever the approach you choose, you need tooling to support you along the way.
-Tooling speeds up process. Tooling enforces semantic. Tooling automates workflow.
-
-There is plenty of offer living around when we talk about diagramming.
-As many come as a SaaS offer, ensure they are compliant with corporate rules (keep in mind we plan to use it to manage our software model which is one of the most valuable IP we have).
-Pick one that at least meet the below facilities.
-
-|||
-|-|-|
-| Library | Most of the diagramming software allow for custom library creation & sharing, which drastically increase newcomer friendliness and thus adoption, while strengthening consistency. A must-have. If you are a Lucidchart user, you may have notice such libraries already exist and can be broadly used (search for C4 in +Shapes menu). |
-| Navigation | Navigate back and forth within your architecture should be a first-class citizen facility. Most of the software support hyperlink, allowing you to seamlessly provide inner (eg C4 levels linking) and outer (eg web url) fast travel. It is a simple but powerful way of enriching your model. |
-| Fast iteration | As said before, design is an iterative process. You need to ensure your tooling friendly plays with fast incremental stages (sketch, save, share). Some also provide advanced facility such as collaborative edition which is a pleasant bonus. |
-
-So, what is the status right now?
-Migrating from plain old whiteboard to a dedicated diagramming software mitigates part of the drawbacks we encounter without sacrificing benefits. We can still keep low cost entry and team centric workflow, while greatly improving edition, management and look & feel.
-This said, some challenges still remain. And they could become painful...
-
-## Remaining challenges
-
-Sketch-first approach is a sustainable one, but it also comes with some limitations that deserve some highlight.
-One could overcome some of those with some discipline and time, but some others could become hard to live with.
-
-|||
-|-|-|
-| Better sustainability but... | Of course, we improve a lot on this field compared to whiteboard snapshotting. Your model is defined through a software that eases daily management. But it is still uncoupled from source code or technical documentation. You need to leverage export that can be difficult to automate and whose staples are images which does not friendly play with source control (versioning, diff., ...). Status is better but far from ideal. |
-| Better resilient to changes but...| It is now far easier to handle CRUD operation. But we still need to live with heavy manual operation that cannot be automated, such as renaming (item must be renamed as many times as existing diagrams it belongs to) and it increases a lot the probability to introduce inconsistency at some point in the model, due to human error. Inconsistent, inaccurate and outdated pieces even if small can spoil the entire model trust, and thus ruin all our effort. |
-| Eye-candy but... | One of the benefit of switching to software to support the diagramming is undoubtedly the prettiness of the outcome. It looks clean and professional whatever our drawing skills. Most of the software accommodates very well zooming (within software, and during export with vector alike format). But that leads to the next aspect, namely display obsession. |
-| Display obsession | Because we are interacting by drag & dropping and connecting shapes, one could be tempted to spend a lot of time to align, sort, resize, tidy up, ... Although this activity participates to increase the overall quality, it is a satellite one and should be handled this way. You are there to tailor software, not to layout to match mood of the day. |
-| Soft control | Applying C4 model and sticking to convention cannot be enforced by diagramming software. Nothing but team review will prevent you to introduce failure. There is no compilation warning, no strongly-typed language, no syntax highlighter or analyzer... It is like coding within Notepad instead of a dedicated IDE. You can manage to succeed but are doomed to collapse someday...|
-| Maintenance | As we do not manage to unify source code, documentation and diagramming (yet), maintenance phase is still blurry. How do we enforce consistency? What is the review workflow (no Pull Request available)? |
-
-## Closing
-
-This post highlights benefits and drawbacks of leveraging sketches to build and convey software architecture.
-We saw that picking this choice does not confine us to plain old whiteboard and how one could overcome most of those limitations leveraging methods and tools. This said, remaining drawbacks are difficult to deal with if we stay on this shore.
+---
+title: Architecture as sketch
+description: >
+ Deep dive sketch first approach, assets and drawbacks.
+weight: 5
+date: '2021-11-05'
+author: Romain Vasseur
+---
+
+We are used to **xxx as code** (deployment as code, architecture as code) stuff or **xxx-first** (view-first, view-model-first) approaches to specify from which end we start a journey or we tackle an issue. It is a very important step as it contrasts how we address a situation, especially the inherent biases we should be aware of and keep under control.
+
+This post will give some insights of the **sketch-first** or **architecture as sketch** approach, stressing out pros and cons of such a method.
+It should be read in parallel with [next one](/docs/code), which will cover the **architecture as code** or **code-first** approach.
+
+Of course, those are the 2 ends of the spectrum. You may end up with mixing the 2 approaches, or shaping an in-between one.
+Choice is yours to pick but remember to make **contextual** decision.
+There is no per say bad choices, provided that you can explain why you made it.
+Thus, the importance of tracking those choices to be able to rewind & replay without be tempting to rewrite the history.
+Luckily, we will cover this topic a bit later in the `Architecture Decision Record` stage.
+
+## Whiteboard
+
+First thing you may have heard about properly touching upon development is to start with a design phase. To stress that point, some advertise to stay away from any form of IDE or computer. Here came the golden age of whiteboarding. A couple of markers and basic drawing skills empower anyone to tailor unmatched diagrams. But nothing is that simple.
+
+Before talking about what are inherent limitations of this approach, let's start with its valuable benefits.
+
+|||
+|-|-|
+| Low prerequisites...| Nothing but a room & a couple of markers to engage... |
+| Quick start-up | Meet & sketch. Straightforward. At least, seems to be... |
+| Team friendly | Gathering in a single place, as a team, focusing all together on a dedicated problem, fosters creativity. |
+
+But reality is rapidly catching up...
+
+What we imagine ending up with...
+
+
+
+... and what we are likely to inherit...
+
+
+
+Very few of us that previously experienced this whiteboard-based design approach can shamelessly say that:
+- They never take a snapshot of a whiteboard for later (and drop it within a pompous MoM email...)
+- They never annotate a cryptic whiteboard with an equally cryptic do not erase (please) for posterity
+- They never entirely rewrite the same sketch multiple times (and often in the same brainstorming session)
+- ...
+
+This first step is very valuable to gauge what we should end up with, and maybe more important what we should avoid ending up with. Despite its apparent simplicity, it appears that crafting valuable materials is not that straightforward, and a bunch of unexpected issues arise...
+
+|||
+|-|-|
+| Lack of sustainability | First move could be a cheap one. But you are doomed to pay penalty for any consecutive ones. Assuming you managed to draft a meaningful diagram, you are stuck with persistence, upcoming checkout and modifications, version tracking, ... |
+| No resilience to changes | Design are inherently incremental and poorly accommodates with whiteboarding. Eg there is no simple way to make room for new piece in an existing sketch. CrUD and layout operations are very costly, as they mostly imply a complete redraw. |
+| Not at all eye-candy | It is difficult but not impossible to sketch nice stuff (but it implies some drawing skills that are not those common). But it is quite impossible to achieve at the first trial, especially when we start from blank page. Whatever the time you spent, you will end up somewhere between a mess & a draft. Do not expect more. |
+
+What is wrong? We started whiteboarding - aka collaborative pen & paper - following the initial advice prescribing to stay away from any form of IDE or computer. At least, that's what we thought. This guideline is not the original one but a poor translation aimed at beginners. And, as often when smart guys try to popularize, misleading.
+**Prevent yourself to code before designing** is the mantra we should stick to.
+Of course, if you do not access neither an IDE nor a computer, you won't be able to code, but is is merely a side-effect...
+
+We all are engineers. Engineers cope with issues with methods and tools.
+We define method 2 chapters ago, spending time to introduce [C4 model](/docs/c4-model) & [convention](/docs/convention).
+It is now time to tailor tools. And software engineers tools are - guess what - software...
+
+## Diagramming software
+
+Whatever the approach you choose, you need tooling to support you along the way.
+Tooling speeds up process. Tooling enforces semantic. Tooling automates workflow.
+
+There is plenty of offer living around when we talk about diagramming.
+As many come as a SaaS offer, ensure they are compliant with corporate rules (keep in mind we plan to use it to manage our software model which is one of the most valuable IP we have).
+Pick one that at least meet the below facilities.
+
+|||
+|-|-|
+| Library | Most of the diagramming software allow for custom library creation & sharing, which drastically increase newcomer friendliness and thus adoption, while strengthening consistency. A must-have. If you are a Lucidchart user, you may have notice such libraries already exist and can be broadly used (search for C4 in +Shapes menu). |
+| Navigation | Navigate back and forth within your architecture should be a first-class citizen facility. Most of the software support hyperlink, allowing you to seamlessly provide inner (eg C4 levels linking) and outer (eg web url) fast travel. It is a simple but powerful way of enriching your model. |
+| Fast iteration | As said before, design is an iterative process. You need to ensure your tooling friendly plays with fast incremental stages (sketch, save, share). Some also provide advanced facility such as collaborative edition which is a pleasant bonus. |
+
+So, what is the status right now?
+Migrating from plain old whiteboard to a dedicated diagramming software mitigates part of the drawbacks we encounter without sacrificing benefits. We can still keep low cost entry and team centric workflow, while greatly improving edition, management and look & feel.
+This said, some challenges still remain. And they could become painful...
+
+## Remaining challenges
+
+Sketch-first approach is a sustainable one, but it also comes with some limitations that deserve some highlight.
+One could overcome some of those with some discipline and time, but some others could become hard to live with.
+
+|||
+|-|-|
+| Better sustainability but... | Of course, we improve a lot on this field compared to whiteboard snapshotting. Your model is defined through a software that eases daily management. But it is still uncoupled from source code or technical documentation. You need to leverage export that can be difficult to automate and whose staples are images which does not friendly play with source control (versioning, diff., ...). Status is better but far from ideal. |
+| Better resilient to changes but...| It is now far easier to handle CRUD operation. But we still need to live with heavy manual operation that cannot be automated, such as renaming (item must be renamed as many times as existing diagrams it belongs to) and it increases a lot the probability to introduce inconsistency at some point in the model, due to human error. Inconsistent, inaccurate and outdated pieces even if small can spoil the entire model trust, and thus ruin all our effort. |
+| Eye-candy but... | One of the benefit of switching to software to support the diagramming is undoubtedly the prettiness of the outcome. It looks clean and professional whatever our drawing skills. Most of the software accommodates very well zooming (within software, and during export with vector alike format). But that leads to the next aspect, namely display obsession. |
+| Display obsession | Because we are interacting by drag & dropping and connecting shapes, one could be tempted to spend a lot of time to align, sort, resize, tidy up, ... Although this activity participates to increase the overall quality, it is a satellite one and should be handled this way. You are there to tailor software, not to layout to match mood of the day. |
+| Soft control | Applying C4 model and sticking to convention cannot be enforced by diagramming software. Nothing but team review will prevent you to introduce failure. There is no compilation warning, no strongly-typed language, no syntax highlighter or analyzer... It is like coding within Notepad instead of a dedicated IDE. You can manage to succeed but are doomed to collapse someday...|
+| Maintenance | As we do not manage to unify source code, documentation and diagramming (yet), maintenance phase is still blurry. How do we enforce consistency? What is the review workflow (no Pull Request available)? |
+
+## Closing
+
+This post highlights benefits and drawbacks of leveraging sketches to build and convey software architecture.
+We saw that picking this choice does not confine us to plain old whiteboard and how one could overcome most of those limitations leveraging methods and tools. This said, remaining drawbacks are difficult to deal with if we stay on this shore.
Check out the next [Architecture as Code](/docs/code) stage to balance what we learned here, and discover a brand-new way of crafting a model.
\ No newline at end of file
diff --git a/docs/content/docs/toolchain.md b/docs/content/docs/toolchain.md
index 3a5b5c2..a5b5c84 100644
--- a/docs/content/docs/toolchain.md
+++ b/docs/content/docs/toolchain.md
@@ -1,16 +1,16 @@
----
-title: Toolchain
-description: >
- Start your code-first approach journey.
-weight: 8
-date: '2021-11-08'
-author: Romain Vasseur
----
-
-Some times ago we introduced the concept of [architecture as code or code-first approach](/docs/code). We took the opportunity to leverage [Structurizr tool suite](/docs/code/#structurizr) to support the end-user journey. However, most of the journey focused on what one could expect to gain from a single model defined as code, without dwelling on how authoring this model for too long.
-
-Authoring file benefits from dedicated tooling. Main objective of such tooling is to support user with edition & validation. We all are used to leverage dedicated IDE when crafting software. Sadly, C4 DSL does not come with first class citizen tooling. To fill this gap, and enforce consistency along the whole workflow, a dedicated [VS Code](https://code.visualstudio.com/) extension has been shaped, aka [Cornifer](https://github.com/rvr06/cornifer). While you could certainly achieve great results by other means, **VS Code + Cornifer** is the recommended stack to draw on.
-
-
-
+---
+title: Toolchain
+description: >
+ Start your code-first approach journey.
+weight: 8
+date: '2021-11-08'
+author: Romain Vasseur
+---
+
+Some times ago we introduced the concept of [architecture as code or code-first approach](/docs/code). We took the opportunity to leverage [Structurizr tool suite](/docs/code/#structurizr) to support the end-user journey. However, most of the journey focused on what one could expect to gain from a single model defined as code, without dwelling on how authoring this model for too long.
+
+Authoring file benefits from dedicated tooling. Main objective of such tooling is to support user with edition & validation. We all are used to leverage dedicated IDE when crafting software. Sadly, C4 DSL does not come with first class citizen tooling. To fill this gap, and enforce consistency along the whole workflow, a dedicated [VS Code](https://code.visualstudio.com/) extension has been shaped, aka [Cornifer](https://github.com/rvr06/cornifer). While you could certainly achieve great results by other means, **VS Code + Cornifer** is the recommended stack to draw on.
+
+
+
Whether you are a seasoned C4 DSL author or plan to start your architecture as code journey, **Cornifer** extension will support you along the way. Coupled with Structurizr engine, it provides a top-notch architecture stack. Give it a try and start contributing to the code-first architecture community.
\ No newline at end of file
diff --git a/docs/content/docs/usage.md b/docs/content/docs/usage.md
index 38e3e05..b9de9b2 100644
--- a/docs/content/docs/usage.md
+++ b/docs/content/docs/usage.md
@@ -1,64 +1,64 @@
----
-title: Usage
-description: >
- Why architecture matters?
-weight: 1
-date: '2021-11-01'
-author: Romain Vasseur
----
-
-## Are you kidding me?
-
-
-
-Not at the same level, not with the same legend, ...
-How one could reasonably make decision such as:
-- Compare left and righ sides
-- Draft coupling between left and righ sides
-- ...
-
-## Now we can talk
-
-Same model, same semantic.
-
-
-
-Time is properly used to discuss content rather than form.
-
-## Adaptive audience control
-
-
-
-As for `MVVM` pattern, we can switch between the most meaningful view for a given `software model`. Model lossless simplification eases identification & comparison (like hashing).
-
-## Spot the differences
-
-
-
-Compare underlying model not layout.
-
-## Layout consistency
-
-
-
-Enforce layout consistency eases the process.
-
-## Gimme the 13mm wrench please
-
-
-
-Identification is the first step for reusability
-
-## Draft’em all at once makes me shine (at least, i believe it does…)®
-
-
-
-- What’s the important feature?
-- What’s the important level?
-- Why this asymmetry or unfairness processing?
-
-## Audience servant®
-
-
-
-Basically, all you can do to ease audience grasping content, rather than losing time & mental overload, must be done.
+---
+title: Usage
+description: >
+ Why architecture matters?
+weight: 1
+date: '2021-11-01'
+author: Romain Vasseur
+---
+
+## Are you kidding me?
+
+
+
+Not at the same level, not with the same legend, ...
+How one could reasonably make decision such as:
+- Compare left and righ sides
+- Draft coupling between left and righ sides
+- ...
+
+## Now we can talk
+
+Same model, same semantic.
+
+
+
+Time is properly used to discuss content rather than form.
+
+## Adaptive audience control
+
+
+
+As for `MVVM` pattern, we can switch between the most meaningful view for a given `software model`. Model lossless simplification eases identification & comparison (like hashing).
+
+## Spot the differences
+
+
+
+Compare underlying model not layout.
+
+## Layout consistency
+
+
+
+Enforce layout consistency eases the process.
+
+## Gimme the 13mm wrench please
+
+
+
+Identification is the first step for reusability
+
+## Draft’em all at once makes me shine (at least, i believe it does…)®
+
+
+
+- What’s the important feature?
+- What’s the important level?
+- Why this asymmetry or unfairness processing?
+
+## Audience servant®
+
+
+
+Basically, all you can do to ease audience grasping content, rather than losing time & mental overload, must be done.