diff --git a/docs/extensions/civix.md b/docs/extensions/civix.md
index 45d201f29f6c6e5b6e8cb36d8633ba004915c67f..5622539e45925f879253a09667afe515641b1104 100644
--- a/docs/extensions/civix.md
+++ b/docs/extensions/civix.md
@@ -173,6 +173,54 @@ basic operations, such as adding a `<select>` element to the form.
CiviCRMs "menu cache". This can be done in a web browser by visiting
`/civicrm/menu/rebuild?reset=1`
+### Add a new entity
+
+!!! caution
+ This functionality is considered "experimental and incomplete".
+
+You may have a need to create a new entity that does not exist in
+CiviCRM. For this, you can use the command `civix generate:entity`
+
+- Pick a name for your entity. In some places, CiviCRM expects a
+ *FirstLetterCapitalizedName*, in others, an *underscore_name*. Be
+ absolutely consistent in your naming, because CiviCRM needs to
+ translate between those two naming conventions.
+
+- Run `civix generate:entity <name of entity>` (entity name should be
+ FirstLetterCapitalized here). This creates a skeletal file for your
+ XML schema, your BAO, and your API. It does NOT create a skeletal
+ SQL file to create your table or DAO files at this time.
+- Edit the XML schema in the `xml` folder to match the fields you
+ want. Minimal documentation is available
+ [here](https://wiki.civicrm.org/confluence/display/CRMDOC/Database+Reference),
+ but you are better off looking at the [existing XML
+ schemata](https://github.com/civicrm/civicrm-core/tree/master/xml/schema).
+- Create a DAO file. For now, civix does not handle this. You can
+ create this by hand. Alternatively, use [this
+ technique](http://civicrm.stackexchange.com/a/3536/12). Copy your
+ XML schema into a development copy of CiviCRM. Edit Schema.xml to
+ include your XML file, then from the xml folder, run
+ `php ./GenCode.php` (In CiviCRM 4.7.12+, run
+ `<civiroot>/bin/setup.sh -g` instead). This will generate a DAO file
+ for you in the CiviCRM core code; copy it into the
+ `CRM/<Entityname>/DAO` folder of your extension.
+- Currently, `civix` does not generate the SQL to create and
+ drop your table(s). You can create these by hand, or, if
+ you used the `<civiroot>/bin/setup.sh -g` technique to create your
+ DAO, SQL will have been generated for you in
+ `<civiroot>/sql/civicrm.mysql`. Once you have the SQL statements for
+ creating and dropping your SQL tables, create
+ `auto_install.sql` and `auto_uninstall.sql`
+ respectively in your 'sql/' folder. CiviCRM will run them
+ automatically on install if you generated an upgrader. Note that
+ using `auto_install.sql` and `auto_uninstall.sql`
+ is not best practice if you have multiple statements in each file,
+ since you cannot error check each statement separately.
+ <!-- fixme update and clarify -->
+- Run `civix generate:upgrader` from within your extension.
+- Define your entity using
+ [hook_civicrm_entityTypes](https://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_entityTypes).
+
### Add a database upgrader, installer and uninstaller
If your module requires creating or maintaining SQL tables, then you
@@ -558,54 +606,6 @@ For use with CiviCRM 4.3, you can also add the `–schedule` option (e.g.
- `api/v3/NewEntity/NewAction.mgd.php` provides the scheduling
record that will appear in the CiviCRM's job-manager.
-### Add a new entity
-
-!!! caution
- This functionality is considered "experimental and incomplete".
-
-You may have a need to create a new entity that does not exist in
-CiviCRM. For this, you can use the command `civix generate:entity`
-
-- Pick a name for your entity. In some places, CiviCRM expects a
- *FirstLetterCapitalizedName*, in others, an *underscore_name*. Be
- absolutely consistent in your naming, because CiviCRM needs to
- translate between those two naming conventions.
-
-- Run `civix generate:entity <name of entity>` (entity name should be
- FirstLetterCapitalized here). This creates a skeletal file for your
- XML schema, your BAO, and your API. It does NOT create a skeletal
- SQL file to create your table or DAO files at this time.
-- Edit the XML schema in the `xml` folder to match the fields you
- want. Minimal documentation is available
- [here](https://wiki.civicrm.org/confluence/display/CRMDOC/Database+Reference),
- but you are better off looking at the [existing XML
- schemata](https://github.com/civicrm/civicrm-core/tree/master/xml/schema).
-- Create a DAO file. For now, civix does not handle this. You can
- create this by hand. Alternatively, use [this
- technique](http://civicrm.stackexchange.com/a/3536/12). Copy your
- XML schema into a development copy of CiviCRM. Edit Schema.xml to
- include your XML file, then from the xml folder, run
- `php ./GenCode.php` (In CiviCRM 4.7.12+, run
- `<civiroot>/bin/setup.sh -g` instead). This will generate a DAO file
- for you in the CiviCRM core code; copy it into the
- `CRM/<Entityname>/DAO` folder of your extension.
-- Currently, `civix` does not generate the SQL to create and
- drop your table(s). You can create these by hand, or, if
- you used the `<civiroot>/bin/setup.sh -g` technique to create your
- DAO, SQL will have been generated for you in
- `<civiroot>/sql/civicrm.mysql`. Once you have the SQL statements for
- creating and dropping your SQL tables, create
- `auto_install.sql` and `auto_uninstall.sql`
- respectively in your 'sql/' folder. CiviCRM will run them
- automatically on install if you generated an upgrader. Note that
- using `auto_install.sql` and `auto_uninstall.sql`
- is not best practice if you have multiple statements in each file,
- since you cannot error check each statement separately.
- <!-- fixme update and clarify -->
-- Run `civix generate:upgrader` from within your extension.
-- Define your entity using
- [hook_civicrm_entityTypes](https://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_entityTypes).
-
### Add a unit-test class
Unit-testing is essential to maintain quality-control over