--- a/docs/pages/support.md	Thu Feb 15 18:36:48 2018 -0800
+++ b/docs/pages/support.md	Thu Feb 15 18:37:06 2018 -0800
@@ -4,8 +4,13 @@
 nav_key: support
 ---
 
+## Changelog
+
 Want to know what's new with PieCrust? Check out the [CHANGELOG][ch].
 
+
+## General Support
+
 If you have a problem with PieCrust, there are a few ways to solve it:
 
 * Check the [documentation][doc] one more time! You never know, the solution may be in
@@ -19,6 +24,48 @@
 * If you have questions, hit the [me][] on [Twitter][].
 
 
+## Upgrading PieCrust
+
+### Version 2 to 3
+
+Several things have changed between version 2 and 3, and some of them introduce
+breaking changes.
+
+#### Generated page templates
+
+Previously, taxonomy listing pages had their template defined as a page with
+a special name. For instance, tag lists were by default defined by
+`pages/_tag.html`.
+
+Now those page templates are proper templates, found in the `templates`
+directory (or other if you changed that). The tag list is now
+`templates/_tag.html` for instance.
+
+In general, you should only have to move your template for the `pages` folder to
+the `templates` folder.
+
+#### Generators
+
+There is no more `generators` in the website configuration -- everything is
+a content source. If you had custom generators in their, you will need to
+re-declare them as standard sources.
+
+For example, a new taxonomy source would be defined like this:
+
+```
+site:
+  sources:
+    post_tags:
+      type: taxonomy
+      taxonomy: tags
+      source: posts
+```
+
+In this example, `tags` is a taxonomy declared the same way as previously inside
+`site/taxonomies`, and `posts` is a normal page source declared also in the same
+way as previously.
+
+
 [doc]: {{docurl('')}}
 [ch]: {{pcurl('support/changelog')}}
 [bbsrc]: https://bitbucket.org/ludovicchabant/piecrust2