diff --git a/markdown/dev/editors/markdown/custom-components/example/en.md b/markdown/dev/editors/markdown/custom-components/example/en.md
index 56668eb9744..bd08b855710 100644
--- a/markdown/dev/editors/markdown/custom-components/example/en.md
+++ b/markdown/dev/editors/markdown/custom-components/example/en.md
@@ -11,7 +11,7 @@ and use is not fully covered below. It's good to know it exists though.
 And if you want to use it, reach out on Discord to some of our more
 experienced documentation writers.
 
-```mdx
+```md
 <Example 
   part="path_attr" 
   caption="Example of the Example custom component" 
diff --git a/markdown/dev/guides/patterns/config/en.md b/markdown/dev/guides/patterns/config/en.md
index 852c2a61bb1..e03570adffa 100644
--- a/markdown/dev/guides/patterns/config/en.md
+++ b/markdown/dev/guides/patterns/config/en.md
@@ -1,6 +1,6 @@
 ---
 title: Configuration
-order: 60
+order: 10
 ---
 
 <Example 
@@ -12,7 +12,11 @@ order: 60
 A pattern's [configuration](/reference/config/) is created by the pattern designer
 and details a number of important things about the pattern, like:
 
- - The measurements that are required to draft the pattern
- - The different parts in the pattern and how they depend on each other
- - The different options that are available to tweak the pattern
+ - The **measurements** that are required to draft the pattern
+ - The different **parts** in the pattern and how they depend on each other
+ - The different **options** that are available to tweak the pattern
 
+The configuration is part of the pattern's code. It is created by the designer and 
+it is the same for everybody using the pattern.
+In other words, you cannot change the configuration. Instead, the configuration
+specifies what kind of settings the pattern accepts.
diff --git a/markdown/dev/guides/patterns/en.md b/markdown/dev/guides/patterns/en.md
index 4582a812c99..503a1045fcb 100644
--- a/markdown/dev/guides/patterns/en.md
+++ b/markdown/dev/guides/patterns/en.md
@@ -1,5 +1,5 @@
 ---
-title: Pattern guide
+title: How patterns work
 order: 200
 for: contributors
 icons: 
@@ -17,6 +17,12 @@ goals:
   - Learn about the pattern itself
 ---
 
+This short guide will illustrate and explain how patterns work in FreeSewing.
+Not to be confused with how sewing pattern work — although there's [great books 
+about that](https://www.assembil.com/how-patterns-work-book/) if you're 
+interested — it's about what goes on under the hood each time a sewing
+pattern is generated by FreeSewing.
+
 This illustration is a good starting point to gain a better 
 understanding of the structure of a FreeSewing pattern:
 
@@ -25,14 +31,15 @@ understanding of the structure of a FreeSewing pattern:
   caption="A schematic overview of FreeSewing"
 />
 
-As you learn more about FreeSewing, you'll discover that there's more
-to this picture than meets the eye. So let's get started.
-
 If we look at our image, it can can divided into three areas:
 
- - The left area with the *settings*  box
- - The middle area with the *Pattern* box and everything in it
- - The right area with the *draft* box and the *SVG* and *React* logos
+ - The left area with the **settings**  box
+ - The middle area with the **Pattern** box and everything in it
+ - The right area with the **draft** box and the *SVG* and *React* logos
+
+Let's take a closer look at everything that is contained within our central **Pattern** box:
+
+<ReadMore list />
 
 <Note>
 
@@ -40,12 +47,8 @@ The left and right parts are all about how to integrate FreeSewing in your *fron
 In other words, how you'll plug it into your website, or online store, or a mobile
 application.
 
-That part is outside the scope of this text.
+That part is outside the scope of this guide.
 
 </Note>
 
-Let's take a closer look at everything that is contained within our central *Pattern* box:
-
-<ReadMore list />
-
 
diff --git a/markdown/dev/guides/patterns/parts/en.md b/markdown/dev/guides/patterns/parts/en.md
index d8a4429cc89..fd99e22e27e 100644
--- a/markdown/dev/guides/patterns/parts/en.md
+++ b/markdown/dev/guides/patterns/parts/en.md
@@ -1,6 +1,6 @@
 ---
 title: Parts
-order: 40
+order: 20
 ---
 
 <Example 
diff --git a/markdown/dev/guides/patterns/paths/en.md b/markdown/dev/guides/patterns/paths/en.md
index 8833a13b64c..d062818a601 100644
--- a/markdown/dev/guides/patterns/paths/en.md
+++ b/markdown/dev/guides/patterns/paths/en.md
@@ -1,6 +1,6 @@
 ---
 title: Paths
-order: 20
+order: 40
 ---
 
 <Example 
diff --git a/markdown/dev/guides/patterns/points/en.md b/markdown/dev/guides/patterns/points/en.md
index 5a240d6ccac..e51704fa2a5 100644
--- a/markdown/dev/guides/patterns/points/en.md
+++ b/markdown/dev/guides/patterns/points/en.md
@@ -1,6 +1,6 @@
 ---
 title: Points
-order: 10
+order: 30
 ---
 
 <Example 
diff --git a/markdown/dev/guides/patterns/snippets/en.md b/markdown/dev/guides/patterns/snippets/en.md
index 02559160f3a..bdd482c57d6 100644
--- a/markdown/dev/guides/patterns/snippets/en.md
+++ b/markdown/dev/guides/patterns/snippets/en.md
@@ -1,6 +1,6 @@
 ---
 title: Snippets
-order: 20
+order: 50
 ---
 
 <Example 
diff --git a/markdown/dev/guides/patterns/store/en.md b/markdown/dev/guides/patterns/store/en.md
index fc4d467818b..d8d399044c9 100644
--- a/markdown/dev/guides/patterns/store/en.md
+++ b/markdown/dev/guides/patterns/store/en.md
@@ -1,6 +1,6 @@
 ---
 title: Store
-order: 70
+order: 60
 ---
 
 <Example 
diff --git a/markdown/dev/guides/prerequisites/bezier-curves/en.md b/markdown/dev/guides/prerequisites/bezier-curves/en.md
index 15ea4f3c829..2e6d22bb552 100644
--- a/markdown/dev/guides/prerequisites/bezier-curves/en.md
+++ b/markdown/dev/guides/prerequisites/bezier-curves/en.md
@@ -1,35 +1,42 @@
 ---
-title: Bézier curves
+title: Understanding Bézier curves
 order: 50
 ---
 
 While lines on computers are easy to store with a start and end point, 
 curves require more information.
+In FreeSewing — as in SVG and countless of other computer applications —
+curves are stored as [Bézier curves](https://en.wikipedia.org/wiki/B%C3%A9zier_curve), 
+named after French engineer [Pierre Bézier](https://en.wikipedia.org/wiki/Pierre_B%C3%A9zier) who 
+popularized their use back in the 1960s.
 
-In FreeSewing — as in SVG and countless of other applications —  
-curves are stored as Bézier curves. They have:
+In FreeSewing, we use so-called cubic Bézier curves which have:
 
  - A start point
  - A first control point that’s linked to the start point
  - A second control point that’s linked to the end point
  - An end point
 
-<Example settings={{complete: false}} part="path_curve" caption="An example of a Bézier curve drawn by the Path.curve() method" />
+<Example settings={{complete: false}} part="path_curve">
+An example of a Bézier curve drawn by the Path.curve() method
+</Example>
 
 Bézier curves and their *handles* or *control points* are surprisingly intuitive. 
 The following illustration does a great job at explaining how they are constructed:
 
 ![How Bézier curves are constructed](bezier.gif)
 
+You don't need understand the mathematics behind Bézier Curves. 
+As long as you intuitively *get* how the control points influence the curve, you're good to go.
+
 <Note>
 
 ###### More on Bézier curves
 
-Wikipedia has a good [introduction to Bézier curves](https://pomax.github.io/bezierinfo/).  
-For a deep-dive into the subject, check out [A Primer on Bézier Curves](https://pomax.github.io/bezierinfo/) by Pomax.
+Wikipedia has a good [introduction to Bézier curves](https://en.wikipedia.org/wiki/B%C3%A9zier_curve).  
+For a deep-dive into the subject, check out [A Primer on Bézier Curves](https://pomax.github.io/bezierinfo/) by 
+[Pomax](https://github.com/Pomax).
 
-Note that you don't need understand the mathematics behind Bézier Curves. 
-As long as you intuitively *get* how the control points influence the curve, you're good to go.
 
 </Note>
 
diff --git a/markdown/dev/guides/prerequisites/coordinate-system/en.md b/markdown/dev/guides/prerequisites/coordinate-system/en.md
index e262ad6ee42..2ce0489ec87 100644
--- a/markdown/dev/guides/prerequisites/coordinate-system/en.md
+++ b/markdown/dev/guides/prerequisites/coordinate-system/en.md
@@ -1,16 +1,17 @@
 ---
-title: Coordinate system
+title: The coordinate system
 order: 30
 ---
 
-In FreeSewing -- and in SVG -- coordinates are like text in a book. 
-You start at the top on the left side, and going to the right 
-and downwards means going ahead.
+The coordinate system in FreeSewing -- and in SVG -- follows the same rules as text on a page.
+You start at the top-left, and as you go to the right, the X-coordinate will increase.
+As you go down the Y-coordinate will increase.
 
 <Example part="docs_coords" caption="The SVG coordinate system" /> 
 
-Which means that on the X-axis, `20` is further to the right than `10`.  
-Likewise, on the Y-axis, `50` is lower than `20`.
+The image above illustrates both the X-axis and Y-axis.
+On the X-axis, `20` is further to the right than `10`.
+On the Y-axis, `50` is lower than `20`.
 
 <Note>
 
diff --git a/markdown/dev/guides/prerequisites/en.md b/markdown/dev/guides/prerequisites/en.md
index 2645400870a..8be7a2ef965 100644
--- a/markdown/dev/guides/prerequisites/en.md
+++ b/markdown/dev/guides/prerequisites/en.md
@@ -1,5 +1,5 @@
 ---
-title: Prerequisites
+title: Before you start
 order: 100
 for: developers
 icons: 
@@ -15,10 +15,12 @@ goals:
   - Learn about Bézier curves
 ---
 
-Here's a few things that, once you get them, will make it easier to understand
-what FreeSewing is doing, and how it's doing it. 
+Drawing lines and curves on paper is a skill most people have been practicing since kindergarten.
+In FreeSewing, we draw lines and curves with code, which is a bit more abstract 
+but doesn't have to be complicated once you understand a few basic building blocks.
 
-We'll cover the following topics:
+Understanding the concepts that are involved in designing sewing patterns in code will pay dividents later.
+That is why we recommend you familiarize yourself with the following topics:
 
 <ReadMore list />
 
diff --git a/markdown/dev/guides/prerequisites/parametric-pattern-design/en.md b/markdown/dev/guides/prerequisites/parametric-pattern-design/en.md
deleted file mode 100644
index f1bc8aa9dd2..00000000000
--- a/markdown/dev/guides/prerequisites/parametric-pattern-design/en.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-title: Parametric pattern design
-order: 10
----
-
-The FreeSewing core library is a toolbox for **parametric pattern design**;
-Using parameters or variables to manipulate the outcome of a given design.
-
-In sewing patterns, the parameters are what is provided by the user: 
-Their measurements and options that they have selected.
-
-<Note>
-
-##### No more grading, ever
-
-When drafting or designing patterns or garments, it is common practice to start 
-with a fit model (or dress form). 
-The measurements of the fit model are used as input in the initial design.
-
-Adapting the pattern for a different model is a tedious task, 
-which is why patterns are graded up and down to cover different sizes.
-
-But in a parametric sewing pattern, adapting to different sizes or models *just works*.
-
-</Note>
-
-FreeSewing patterns are implemented **as code**, which has a lot of advantages.
-
-It allows for patterns that adapt to your measurements or preferences, 
-fine-grained version control, seamless collaboration, and using existing
-patterns as a starting point for you own, to name but a few.
-
-That being said, you don't have to be a code monkey to use FreeSewing.
-
diff --git a/markdown/dev/guides/prerequisites/svg/en.md b/markdown/dev/guides/prerequisites/svg/en.md
index 929bcf64c07..5bc9ab91bc8 100644
--- a/markdown/dev/guides/prerequisites/svg/en.md
+++ b/markdown/dev/guides/prerequisites/svg/en.md
@@ -1,12 +1,11 @@
 ---
-title: SVG
+title: Scalable Vector Graphics
 order: 20
 ---
 
-Patterns are rendered as SVG — short
+Patterns are rendered as **SVG** — short
 for [Scalable Vector Graphics](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) —
 an XML-based vector image format and an open standard.
-
 While you don’t need to be an SVG expert, a basic understanding of the format 
 will greatly help you to understand FreeSewing.
 
diff --git a/markdown/dev/guides/prerequisites/units/en.md b/markdown/dev/guides/prerequisites/units/en.md
index 12a08e71c7a..e45a1eda904 100644
--- a/markdown/dev/guides/prerequisites/units/en.md
+++ b/markdown/dev/guides/prerequisites/units/en.md
@@ -1,13 +1,16 @@
 ---
-title: Units
+title: Units in FreeSewing
 order: 40
 ---
 
-Internally, freesewing uses millimeter. 
+FreeSewing uses millimeter for all its internal units. 
+We do support both imperial and metrics units, which are displayed
+as cm or inch, but under the hood everything is handled in millimeter.
+
+So as a pattern designer, you will work with mm.
 When you write `1`, that’s one mm. When you write `7.8`, that’s 7.8mm.
 
 While you can use cm or inch on the FreeSewing website, that is merely a layer of 
 abstration on top of the internal units, which are always mm.
 
-So as a pattern designer, you will work with mm.
 
diff --git a/markdown/dev/reference/api/part/shorthand/en.md b/markdown/dev/reference/api/part/shorthand/en.md
index cee551d0941..b7b13319786 100644
--- a/markdown/dev/reference/api/part/shorthand/en.md
+++ b/markdown/dev/reference/api/part/shorthand/en.md
@@ -43,7 +43,7 @@ The `Part.shorthand()` method returns a plain object with the following properti
 
 ## Part.shorthand() example
 
-```js{16}
+```js
 // You could write this:
 part.points.from = new part.Point(
   pattern.measurements.chest / 2, 
diff --git a/markdown/dev/reference/snippets/bnotch/en.md b/markdown/dev/reference/snippets/bnotch/en.md
index 89295b017a0..9d93dfbb1c0 100644
--- a/markdown/dev/reference/snippets/bnotch/en.md
+++ b/markdown/dev/reference/snippets/bnotch/en.md
@@ -11,5 +11,5 @@ It is provided by [plugin-theme](/reference/plugins/theme/).
 snippets.demo = new Snippet('bnotch', points.anchor)
 ```
 
-<Example part="snippets_bnotch" caption="An example of the bnotch snippet" />
+<Example part="snippets_bnotch">An example of the bnotch snippet</Example>
 
diff --git a/markdown/dev/tutorials/pattern-design/create-freesewing-pattern/en.md b/markdown/dev/tutorials/pattern-design/create-freesewing-pattern/en.md
index 99108951534..0bff7cab4ed 100644
--- a/markdown/dev/tutorials/pattern-design/create-freesewing-pattern/en.md
+++ b/markdown/dev/tutorials/pattern-design/create-freesewing-pattern/en.md
@@ -38,7 +38,7 @@ This will take a few minutes because we're loading some software for your develo
 
 When it's ready, enter the directory that was just created for our `tutorial` pattern and navigate to the `example` subfolder. There, start the development environment:
 
-```bash:
+```bash
 cd tutorial/example
 npm start
 ```
diff --git a/markdown/dev/tutorials/pattern-design/en.md b/markdown/dev/tutorials/pattern-design/en.md
index c6df0c6d683..461b35be983 100644
--- a/markdown/dev/tutorials/pattern-design/en.md
+++ b/markdown/dev/tutorials/pattern-design/en.md
@@ -31,7 +31,7 @@ Your focus today is on learning FreeSewing and how to translate your designs int
 
 At the end of this tutorial, you will have created this pattern:
 
-<Example pattern="tutorial" part="bib" caption="Your end result" />
+<Example pattern="tutorial" part="bib">Your end result</Example>
 
 Before we can get started, let's make sure you have the required software 
 installed on your computer:
diff --git a/markdown/dev/tutorials/pattern-design/testing-your-pattern/en.md b/markdown/dev/tutorials/pattern-design/testing-your-pattern/en.md
index c287b4ffe9e..0df2001aaa6 100644
--- a/markdown/dev/tutorials/pattern-design/testing-your-pattern/en.md
+++ b/markdown/dev/tutorials/pattern-design/testing-your-pattern/en.md
@@ -1,5 +1,5 @@
 ---
-title: Testing your pattern
+title: "Testing your pattern"
 order: 250
 ---