From dee15a64e3c2a5aaf4650935bbc008b76c232629 Mon Sep 17 00:00:00 2001
From: Leo Horie <leohorie@hotmail.com>
Date: Wed, 24 Aug 2016 10:46:44 -0400
Subject: [PATCH] doc improvements

---
 docs/fragment.md | 11 ++++++++---
 docs/route.md    |  2 +-
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/docs/fragment.md b/docs/fragment.md
index 653fc828..77c2b854 100644
--- a/docs/fragment.md
+++ b/docs/fragment.md
@@ -23,9 +23,11 @@ Argument    | Type                 | Required | Description
 
 ### How it works
 
-`m.fragment()` creates a [fragment vnode](vnodes.md) with attributes. It is meant for advanced use cases involving keys or lifecyle methods.
+`m.fragment()` creates a [fragment vnode](vnodes.md) with attributes. It is meant for advanced use cases involving [keys](keys.md) or [lifecyle methods](lifecycle-methods.md).
 
-Normally you can use simple arrays instead to denote a list of child nodes or a range of nodes within a node list:
+A fragment vnode represents a list of DOM elements. If you want a regular element vnode that represents only one DOM element, you should use [`m()`](hyperscript.md) instead.
+
+Normally you can use simple arrays instead to denote a list of nodes:
 
 ```javascript
 var groupVisible = true
@@ -34,10 +36,13 @@ m("ul", [
 	m("li", "child 1"),
 	m("li", "child 2"),
 	groupVisible ? [
+		// a fragment containing two elements
 		m("li", "child 3"),
 		m("li", "child 4"),
 	] : null
 ])
 ```
 
-There are a few benefits that come from using `m.fragment` instead of handwriting a vnode object structure: m.fragment creates [monomorphic objects](vnodes.md#monomorphic-objects), which have better performance characteristics than creating objects dynamically. In addition, using `m.fragment` makes your intentions clear, and it makes it less likely that you'll mistakenly set attributes on the vnode object rather than on the attrs object.
\ No newline at end of file
+However, Javascript arrays cannot be keyed or hold lifecycle methods. One option would be to create a wrapper element to host the key or lifecycle method, but sometimes it is not desirable to have an extra element (for example in complex table structures). In those cases, a fragment vnode can be used instead.
+
+There are a few benefits that come from using `m.fragment` instead of handwriting a vnode object structure: m.fragment creates [monomorphic objects](vnodes.md#monomorphic-objects), which have better performance characteristics than creating objects dynamically. In addition, using `m.fragment` makes your intentions clear to other developers, and it makes it less likely that you'll mistakenly set attributes on the vnode object itself rather than on its `attrs` map.
\ No newline at end of file
diff --git a/docs/route.md b/docs/route.md
index fd957f17..64659975 100644
--- a/docs/route.md
+++ b/docs/route.md
@@ -386,7 +386,7 @@ m.route(document.body, "/", {
 
 However, realistically, in order for that to work on a production scale, it would be necessary to bundle all of the dependencies for the `Home.js` module into the file that is ultimately served by the server.
 
-Fortunately, there are a number of tools that facilitate the task of bundling modules for lazy loading. Here's an example using webpack's code splitting system:
+Fortunately, there are a number of tools that facilitate the task of bundling modules for lazy loading. Here's an example using [webpack's code splitting system](https://webpack.github.io/docs/code-splitting.html):
 
 ```javascript
 m.route(document.body, "/", {