doc improvements

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.
+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.