improve docs

docs/benchmarks.md

@@ -4,7 +4,7 @@ These benchmarks were designed to measure Javascript running time for Mithril in
 
 The numbers shown here are best-run results for all frameworks, except for Mithril's case, for which I'm taking the worst-run result. The numbers aren't statistically rigorous (e.g. I didn't bother to calculate standard deviation), but they should be enough to give a rough idea of what is faster than what.
 
-Generally speaking, these tests are making a deliberate effort to be **biased in favor of other frameworks:** for example, I don't load "optional-but-usually-used-in-real-life" things like the router module for Angular, or Marionette in Backbone's case, and I load the entirety of Mithril. In addition, this test deliberately avoids triggering `requestAnimationFrame`-based performance optimizations for Mithril, since this optimization does not exist in many frameworks and [*severely* skews numbers in Mithril's favor](http://jsperf.com/angular-vs-knockout-vs-ember/308) in CPU-intensive situations like parallax sites. I'm also NOT using the [Mithril template compiler](compiling-templates.md), which would also skew the benchmark in Mithril's favor.
+Generally speaking, these tests are making a deliberate effort to be **biased in favor of other frameworks:** for example, I don't load "optional-but-usually-used-in-real-life" things like the router module for Angular, or Marionette in Backbone's case, and I load the entirety of Mithril. In addition, this test deliberately avoids triggering `requestAnimationFrame`-based performance optimizations for Mithril, since this optimization does not exist in many frameworks and [*severely* skews numbers in Mithril's favor](http://jsperf.com/angular-vs-knockout-vs-ember/308) in CPU-intensive situations like parallax sites. I'm also NOT using the [Mithril template compiler](optimizing-performance.md#compiling-templates), which would also skew the benchmark in Mithril's favor.
 
 To run the execution time tests below, click on their respective links, run the profiler from your desired browser's developer tools and measure the running time of a page refresh (lower is better).
 

docs/getting-started.md

@@ -116,21 +116,24 @@ In the case of our todo application, the view-model needs a few things: it needs
 
 ```javascript
 //define the view-model
-todo.vm = {}
-todo.vm.init = function() {
-	//a running list of todos
-	this.list = new todo.TodoList();
-	
-	//a slot to store the name of a new todo before it is created
-	this.description = m.prop("");
-	
-	//adds a todo to the list, and clears the description field for user convenience
-	this.add = function(description) {
-		if (description()) {
-			this.list.push(new todo.Todo({description: description()}));
-			this.description("");
-		}
-	};
+todo.vm = new function() {
+	var vm = {}
+	vm.init = function() {
+		//a running list of todos
+		vm.list = new todo.TodoList();
+		
+		//a slot to store the name of a new todo before it is created
+		vm.description = m.prop("");
+		
+		//adds a todo to the list, and clears the description field for user convenience
+		vm.add = function(description) {
+			if (description()) {
+				vm.list.push(new todo.Todo({description: description()}));
+				vm.description("");
+			}
+		};
+	}
+	return vm
 }
 ```
 
@@ -312,10 +315,10 @@ Mithril uses them in other interesting ways elsewhere.
 Clever readers will probably notice that we can refactor the `add` method to make it much simpler:
 
 ```javascript
-this.add = function() {
-	if (this.description()) {
-		this.list.push(new todo.Todo({description: this.description()}));
-		this.description("");
+vm.add = function() {
+	if (vm.description()) {
+		vm.list.push(new todo.Todo({description: vm.description()}));
+		vm.description("");
 	}
 }.bind(this);
 ```
@@ -430,18 +433,25 @@ todo.TodoList = Array;
 //stores a description for new todos before they are created
 //and takes care of the logic surrounding when adding is permitted
 //and clearing the input after adding a todo to the list
-todo.vm = {}
-todo.vm.init = function() {
-	this.list = new todo.TodoList();
-	this.description = m.prop("");
-	
-	this.add = function() {
-		if (this.description()) {
-			this.list.push(new todo.Todo({description: this.description()}));
-			this.description("");
-		}
-	}.bind(this);
-};
+todo.vm = new function() {
+	var vm = {}
+	vm.init = function() {
+		//a running list of todos
+		vm.list = new todo.TodoList();
+		
+		//a slot to store the name of a new todo before it is created
+		vm.description = m.prop("");
+		
+		//adds a todo to the list, and clears the description field for user convenience
+		vm.add = function() {
+			if (vm.description()) {
+				vm.list.push(new todo.Todo({description: vm.description()}));
+				vm.description("");
+			}
+		};
+	}
+	return vm
+}
 
 //the controller defines what part of the model is relevant for the current page
 //in our case, there's only one view-model that handles everything
@@ -578,7 +588,7 @@ Mithril provides a few more facilities that are not demonstrated in this page. T
 
 ## Advanced Topics
 
--	[Compiling templates](compiling-templates)
+-	[Optimizing performance](optimizing-performance.md)
 -	[Integrating with the Auto-Redrawing System](auto-redrawing.md)
 -	[Integrating with Other Libraries](integration.md)
 

docs/layout/guide.html

@@ -34,7 +34,7 @@
 							<ul>
 								<li><a href="auto-redrawing.html">The Auto-Redrawing System</a></li>
 								<li><a href="integration.html">Integrating with Other Libraries</a></li>
-								<li><a href="compiling-templates.html">Compiling Templates</a></li>
+								<li><a href="optimizing-performance.html">Compiling Templates</a></li>
 							</ul>
 							<h2 id="misc">Misc</h2>
 							<ul>

docs/mithril.module.md

@@ -8,7 +8,12 @@
 
 ---
 
-A module is an Object with two keys: `controller` and `view`. Each of those should point to a Javascript function.
+A module is an Object with two keys: `controller` and `view`. Each of those should point to a Javascript function. Note that the name of both properties should be lower-cased.
+
+```javascript
+//a valid module
+{controller: function() {}, view: function() {}}
+```
 
 When using `m.module`, Mithril instantiates controllers as if they were class constructors. However, controllers may return objects if you want to use that Javascript feature to have more fine-grained control over a controller's lifecycle.
 

docs/optimizing-performance.md

@@ -1,4 +1,14 @@
-## Compiling Templates
+## Optimizing Performance
+
+There's a number of ways to improve Mithril performance for the rare cases where pages are too complex for their own good.
+
+First and foremost, you should think hard about whether performance optimization is truly your last resort. By nature, optimizing performance make aggressive assumptions that can break in edge cases and it yields difficult to understand code. As a rule of thumb, you should *never* implement performance optimizations if another solution is available.
+
+For example, if you are building a table with thousands of rows and finding that the template is slow, you should first consider making the table show less items, because from a user experience perspective, no one is realistically going to scan through thousands of records. The effort to make the table paginated, searchable or filterable can improve the user experience in addition to solving the performance problem both on redraws and on initial page load.
+
+---
+
+## Compiling templates
 
 You can optionally pre-compile templates that use `m()` by running the [`template-compiler.sjs`](tools/template-compiler.sjs) macro with [Sweet.js](https://github.com/mozilla/sweet.js). This step isn't required in order to use Mithril, but it's an easy way to squeeze a little bit more performance out of an application, without the need for code changes.
 

docs/practices.md

@@ -114,4 +114,7 @@ In addition, note that template performance, both in Mithril templates as well a
 
 ## Usage of keys
 
-If you need to sort lists, or delete items from them, or splice them in any way, you should [use the `key` attribute](mithril.md#dealing-with-sorting-and-deleting-in-lists) to maintain referential integrity between the data and the DOM.
+If you need to sort lists, or delete items from them, or splice them in any way, you should [use the `key` attribute](mithril.md#dealing-with-sorting-and-deleting-in-lists) to maintain referential integrity between the data and the DOM.
+
+Not using keys still works in some cases, but might trigger more expensive code paths within the redrawing algorithm.
+

docs/tools.md

@@ -37,7 +37,7 @@ This tool is also available as a [Rails gem](https://github.com/mrsweaters/mithr
 
 You can pre-compile Mithril templates to make them run faster. For more information see this page:
 
-[Compiling Templates](compiling-templates.md)
+[Compiling Templates](optimizing-performance.md#compiling-templates)
 
 ---