diff --git a/markdown/dev/reference/api/snippet/attr/en.md b/markdown/dev/reference/api/snippet/attr/en.md
index 192990d2e73..ac1a7b83bbc 100644
--- a/markdown/dev/reference/api/snippet/attr/en.md
+++ b/markdown/dev/reference/api/snippet/attr/en.md
@@ -1,7 +1,16 @@
 ---
-title: attr()
+title: Snippet.attr()
 ---
 
+The `Snippet.attr()` method can be used to add attributes to the Snippet
+object.  It calls `this.attributes.add()` under the hood, and returns the
+Snippet object.
+
+If the third parameter is set to `true` it will call `this.attributes.set()`
+instead, thereby overwriting the value of the attribute.
+
+## Signature
+
 ```js
 Snippet snippet.attr(
   string name, 
@@ -10,21 +19,25 @@ Snippet snippet.attr(
 )
 ```
 
-This `Snippet.attr()` method calls [`Attributes.add()`](/reference/api/attributes/add) under the hood,
-but returns the Snippet object.  This allows you to chain different calls together.
+<Tip compact>This method is chainable as it returns the `Snippet` object</Tip>
 
-If the third parameter is set to `true` it will call [`Attributes.set()`](/reference/api/attributes/set) instead,
-thereby overwriting the value of the attribute.
+## Example
 
-<Example part="snippet_attr">
-An example of the Snippet.attr() method
+<Example caption="An example of the Snippet.attr() method">
+```js
+({ Point, points, Path, paths, Snippet, snippets, part }) => {
+
+  snippets.logo = new Snippet('logo', new Point(0,0))
+    .attr("data-scale", 0.75)
+    .attr("data-rotate", 180)
+
+  // Prevent clipping
+  paths.diag = new Path()
+    .move(new Point(-25,-10))
+    .move(new Point(25,35))
+
+  return part
+}
+```
 </Example>
 
-```js
-let { Point, points, Snippet, snippets } = part.shorthand();
-
-points.anchor = new Point(50, 15);
-snippets.demo = new Snippet("logo", points.anchor)
-  .attr("data-scale", 0.8)
-  .attr("data-rotate", 180);
-```
diff --git a/markdown/dev/reference/api/snippet/clone/en.md b/markdown/dev/reference/api/snippet/clone/en.md
index fbf3afcec1d..88f400969f3 100644
--- a/markdown/dev/reference/api/snippet/clone/en.md
+++ b/markdown/dev/reference/api/snippet/clone/en.md
@@ -1,25 +1,36 @@
 ---
-title: clone()
+title: Snippet.clone()
 ---
 
+The `Snippet.clone()` method returns a new Snippets object that is a deep copy
+of this one.
+
+## Signature
+
 ```js
 Snippet snippet.clone()
 ```
 
-Returns a new Snippets object that is a deep copy of this one.
+## Example
 
-<Example part="snippet_clone">
-An example of the Snippet.clone() method
+<Example caption="An example of the Snippet.clone() method">
+```js
+({ Point, Path, paths, Snippet, snippets, part }) => {
+
+  snippets.demo = new Snippet("logo", new Point(0,0))
+    .attr("style", "color: #f006")
+  
+  snippets.clone = snippets.demo
+    .clone()
+    .attr("data-scale", 0.5)
+
+  // Prevent clipping
+  paths.diag = new Path()
+    .move(new Point(-25,-30))
+    .move(new Point(25,15))
+
+  return part
+}
+```
 </Example>
 
-```js
-let { Point, points, Snippet, snippets } = part.shorthand();
-
-points.anchor = new Point(35, 35);
-snippets.demo = new Snippet("logo", points.anchor)
-  .attr("style", "color: #f006");
-
-snippets.clone = snippets.demo
-  .clone()
-  .attr("data-scale", 0.5);
-```
diff --git a/markdown/dev/reference/api/snippet/en.md b/markdown/dev/reference/api/snippet/en.md
index 1a3d9194a89..2a9cd0fb09d 100644
--- a/markdown/dev/reference/api/snippet/en.md
+++ b/markdown/dev/reference/api/snippet/en.md
@@ -3,17 +3,21 @@ title: Snippet
 order: 35
 ---
 
-A snippet is a reuseable bit of markup for your pattern. They are added to the
+A Snippet is a reuseable bit of markup for your pattern. They are added to the
 SVG `defs` section, and rendered with the SVG `use` tag.
 
+## Signature
+
+```js
+Snippet new Snippet(def, Point);
+```
+
 The snippet constructor takes two arguments:
 
 - `def` : The `xlink:href` id that links to the relevant entry in the SVG `defs` section
 - `anchor` : A [`Point`](/reference/api/point) on which to anchor the snippet
 
-```js
-Snippet new Snippet(def, Point);
-```
+## Attributes
 
 A Snippet object comes with the following properties:
 
@@ -21,6 +25,26 @@ A Snippet object comes with the following properties:
 - `anchor` : A [`Point`](/reference/api/point) on which to anchor the snippet
 - `attributes` : An [`Attributes`](/reference/api/attributes) instance holding the snippet's attributes
 
-In addition, a Snippet object exposes the following methods:
+## Example
+
+<Example caption="Example of the Snippet constructor">
+```js
+({ Point, Snippet, snippets, Path, paths, part }) => {
+
+  snippets.logo = new Snippet('logo', new Point(0,0))
+
+  // Prevent clipping
+  paths.diag = new Path()
+    .move(new Point(-25,-40))
+    .move(new Point(25,15))
+
+  return part
+}
+```
+</Example>
+
+## Methods
+
+A Snippet object exposes the following methods:
 
 <ReadMore list />