diff --git a/docs/extensions/advanced.md b/docs/extensions/advanced.md
new file mode 100644
index 0000000000000000000000000000000000000000..e6cc5ec0f3387a05794e5d3140d9ed23555eb225
--- /dev/null
+++ b/docs/extensions/advanced.md
@@ -0,0 +1,83 @@
+# Advanced patterns
+
+[]( FIXME remove this banner after review)
+>> NOTE: Some of these instruction maybe deprecated and superceded by better
+>> approaches.
+
+## Web Services
+
+There are three options to create an ajax or web-service callback:
+
+- **Full control:**Add a basic page. Remove the parent::run() call
+ from the run() function, and at the bottom of the run() function,
+ perform your own output (eg "*echo json\_encode($data)*") and then
+ short-circuit processing (eg "*CRM\_Utils\_System::civiExit()*") so
+ that neither Smarty nor the CMS modify the output.
+- **Using ajax helpers (CiviCRM 4.5 and above**): Generate a page with
+ civix as above. Build your data in the run() function. If the
+ client-side request includes *snippet=json* in the url, just append
+ your data to *$this-\>ajaxResponse* array and the rest will happen
+ automatically. If not, you can directly call
+ CRM\_Core\_Page\_AJAX::returnJsonResponse() at the bottom of the run
+ function. See [Ajax Pages and
+ Forms](/confluence/display/CRMDOC/Ajax+Pages+and+Forms)
+ documentation.
+- **Using the API:** Add an API function using `civix`.
+ The API function can be called with the API's [AJAX
+ Interface](http://wiki.civicrm.org/confluence/display/CRMDOC/AJAX+Interface).
+ This automatically handles issues like encoding and decoding the
+ request/response.
+
+## Standalone PHP scripts
+
+Instead of creating a standalone script, consider one of these options:
+
+- Add an API function (using the instructions above). The API function
+ can be called many different ways – cv, PHP, REST, AJAX, CLI, Drush,
+ Smarty, cron, etc. CiviCRM used to include a number of standalone
+ scripts – many of these have been migrated to API functions because
+ this approach is simpler and more flexible.
+- Add a basic page (using the instructions above). At the bottom of
+ the run() function, call "*CRM\_Utils\_System::civiExit()*" to
+ short-circuit theming and CMS processing.
+
+Creating a pure standalone PHP script is a tricky proposition and likely to be
+brittle compared with the above.
+
+If the script is truly standalone and
+does not require any services from the CRM or CMS, then you can just add a
+new `.php` file to the extension... but it won't have access to CiviCRM's
+APIs, databases, classes, etc. If the standalone script needs those
+services, then it will need to ***bootstrap*** CiviCRM and the CMS. This
+is challenging for several reasons:
+
+- The bootstrap mechanics are different in each CMS (Drupal, Joomla,
+ etc).
+- The bootstrap mechanics are different for single-site installations
+ and multi-site installations
+- To initiate a bootstrap from a script, one needs to determine the
+ local-path to the CiviCRM settings. However, the local-path of the
+ script is entirely independent of the local-path to the settings –
+ these are determined at the discretion of the site administrator.
+
+If you really need to do it, it's theoretically possibly to emulate an
+example like
+"[bin/deprecated/EmailProcessor.php](http://svn.civicrm.org/civicrm/branches/v4.1/bin/deprecated/EmailProcessor.php)".
+The results will likely be difficult for downstream users to
+install/use.
+
+
+## Cron jobs
+
+One can add an API function (using the instructions above) and create a
+schedule record. In CiviCRM 4.3, the schedule record can be
+automatically created; to do this, call "civix
+[generate:api](http://generateapi)" with the option "–schedule Daily"
+(or "-schedule Hourly", etc). CiviCRM will make a best-effort to meet
+the stated schedule.
+
+In CiviCRM 4.2, one can use APIs as cron jobs, but the schedule record
+won't be created automatically. The site administrator must manually
+insert a scheduling record by navigating to "Administer =\> System
+Settings =\> Scheduled Jobs".
+
diff --git a/docs/extensions/civix.md b/docs/extensions/civix.md
index 128427d04221c7cf8a4583ca44e51a940eeb40b7..95f3a4a678f27d35bd3d8b774863262a8f4d3e6f 100644
--- a/docs/extensions/civix.md
+++ b/docs/extensions/civix.md
@@ -545,101 +545,3 @@ how to write a test class:
PHPUnit.](https://phpunit.de/manual/current/en/writing-tests-for-phpunit.html)
- Review the example code in
[org.civicrm.exampletests](https://github.com/totten/org.civicrm.exampletests)
-
-# Frequently asked questions
-
-### How does one add an ajax/web-service callback?
-
-There are three options:
-
-- **Full control:**Add a basic page. Remove the parent::run() call
- from the run() function, and at the bottom of the run() function,
- perform your own output (eg "*echo json\_encode($data)*") and then
- short-circuit processing (eg "*CRM\_Utils\_System::civiExit()*") so
- that neither Smarty nor the CMS modify the output.
-- **Using ajax helpers (CiviCRM 4.5 and above**): Generate a page with
- civix as above. Build your data in the run() function. If the
- client-side request includes *snippet=json* in the url, just append
- your data to *$this-\>ajaxResponse* array and the rest will happen
- automatically. If not, you can directly call
- CRM\_Core\_Page\_AJAX::returnJsonResponse() at the bottom of the run
- function. See [Ajax Pages and
- Forms](/confluence/display/CRMDOC/Ajax+Pages+and+Forms)
- documentation.
-- **Using the API:** Add an API function using the instructions above.
- The API function can be called with the API's [AJAX
- Interface](http://wiki.civicrm.org/confluence/display/CRMDOC/AJAX+Interface).
- This automatically handles issues like encoding and decoding the
- request/response.
-
-### How does one add a standalone PHP script?
-
-This is tricky proposition. If the script is truly standalone and
-doesn't require any services from the CRM/CMS, then you can just add a
-new .php file to the extension... but it won't have access to CiviCRM's
-APIs, databases, classes, etc. If the standalone script needs those
-services, then it will need to ***bootstrap*** CiviCRM and the CMS. This
-is challenging for several reasons:
-
-- The bootstrap mechanics are different in each CMS (Drupal, Joomla,
- etc).
-- The bootstrap mechanics are different for single-site installations
- and multi-site installations
-- To initiate a bootstrap from a script, one needs to determine the
- local-path to the CiviCRM settings. However, the local-path of the
- script is entirely independent of the local-path to the settings –
- these are determined at the discretion of the site administrator.
-
-If you really need to do it, it's theoretically possibly to emulate an
-example like
-"[bin/deprecated/EmailProcessor.php](http://svn.civicrm.org/civicrm/branches/v4.1/bin/deprecated/EmailProcessor.php)".
-The results will likely be difficult for downstream users to
-install/use.
-
-Instead of creating a standalone script, consider one of these options:
-
-- Add an API function (using the instructions above). The API function
- can be called many different ways – PHP, REST, AJAX, CLI, Drush,
- Smarty, cron, etc. CiviCRM used to include a number of standalone
- scripts – many of these have been migrated to API functions because
- this approach is simpler and more flexible.
-- Add a basic page (using the instructions above). At the bottom of
- the run() function, call "*CRM\_Utils\_System::civiExit()*" to
- short-circuit theming and CMS processing.
-
-### How does one add a cron job?
-
-One can add an API function (using the instructions above) and create a
-schedule record. In CiviCRM 4.3, the schedule record can be
-automatically created; to do this, call "civix
-[generate:api](http://generateapi)" with the option "–schedule Daily"
-(or "-schedule Hourly", etc). CiviCRM will make a best-effort to meet
-the stated schedule.
-
-In CiviCRM 4.2, one can use APIs as cron jobs, but the schedule record
-won't be created automatically. The site administrator must manually
-insert a scheduling record by navigating to "Administer =\> System
-Settings =\> Scheduled Jobs".
-
-# Troubleshooting
-
-1. I've created the files and edited them but I don't see the expected
- changes.\
- A: Did you install and enable your extension?
- (<site\>/civicrm/admin/extensions?reset=1)\
- \
-
-2. I get Error: "Cannot instantiate API client -- please set connection
- options in parameters.yml"\
- A: You might have missed the step about setting
- 'civicrm\_api3\_conf\_path'
- ([https://github.com/totten/civix/](https://github.com/totten/civix/)),
- or it didn't get set properly for some reason.\
- \
-3. I've tried to generate a page/report/search/upgrader/etc but it's
- not working.\
- A: For all of the various types, you must first run
- [generate:module](http://generatemodule), and then \`cd\` into the
- folder (e.g. com.example.myextension) before running one of the
- other \`generate:\` commands.
-
diff --git a/docs/extensions/troubleshooting.md b/docs/extensions/troubleshooting.md
new file mode 100644
index 0000000000000000000000000000000000000000..ec4cf4a7b6ff9e1d8d8fe146d6d0e743d63eec18
--- /dev/null
+++ b/docs/extensions/troubleshooting.md
@@ -0,0 +1,42 @@
+# Troubleshooting
+
+If you are struggling, the best thing to do is reach out to the
+[CiviCRM community](../basics/community).
+
+If you cannot find the answer in this guide or by searching in the
+[CiviCRM StackExchange site](http://civicrm.stackexchange.com/)
+then please [ask](http://civicrm.stackexchange.com/questions/ask). Asking
+questions on StackExchange not only helps you but may well help others who
+follow you.
+
+That said, this is a small list of some of the commoner problems extension
+writers encounter.
+
+## Extension not doing anything
+
+[]( ###### arguably this list should be removed altogether?? #### )
+
+Q: I've created the files and edited them but I don't see the expected
+changes.
+
+A: Did you install and enable your extension?
+(<site\>/civicrm/admin/extensions?reset=1)
+
+## Civix error messages
+
+Q: I get Error: "Cannot instantiate API client -- please set connection
+options in parameters.yml"
+
+A: You might have missed the step about setting
+'civicrm\_api3\_conf\_path'
+([https://github.com/totten/civix/](https://github.com/totten/civix/)),
+or it didn't get set properly for some reason.
+
+Q: I've tried to generate a page/report/search/upgrader/etc with civix
+but it's not working.
+
+A: For all of the various types, you must first run
+[generate:module](http://generatemodule), and then \`cd\` into the
+folder (e.g. com.example.myextension) before running one of the
+other \`generate:\` commands.
+
diff --git a/mkdocs.yml b/mkdocs.yml
index 83a3dc142520047231e65b680fa7133f177f92ee..616a5fbfb444e7b2e06969810634a0a20f2ab8cc 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -25,8 +25,10 @@ pages:
- All Available Hooks: hooks-db.md
- Writing Extensions:
- Basics: extensions/basics.md
- - civix: extensions/civix.md
+ - Using civix: extensions/civix.md
- Anatomy of Files: extensions/files.md
+ - Advanced Patterns: extensions/advanced.md
+ - Troubleshooting: extensions/troubleshooting.md
# - Using hooks: extensions/using-hooks.md
# - Customizing Screens: extensions/customize-screens.md
# - Creating Pages: Forms/extensions/create-page.md