docs/extensions/troubleshooting.md

 # Troubleshooting
 
-If you are struggling, the best thing to do is reach out to the [CiviCRM community](/basics/community.md).
+If you are struggling, the best thing to do is reach out to the [CiviCRM community](../basics/community.md).
 
 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.
 
@@ -22,5 +22,10 @@ A: You might have missed the step about setting 'civicrm\_api3\_conf\_path' ([ht
 
 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.
+A: For all of the various types, you must first run [generate:module](civix.md#generate-module), and then \`cd\` into the folder (e.g. com.example.myextension) before running one of the other \`generate:\` commands.
 
+## Out-of-date templates
+
+Many of the generators in `civix` rely on helpers and stubs defined in `<mymodule>.php` or `<mymodule>.civix.php`. If you
+run `civix generate:*` on an older extension and have trouble with the generated code, then review [UPGRADE.md](https://github.com/totten/civix/blob/master/UPGRADE.md)
+for (a) general upgrade procedures and (b) a list of specific changes that could require manual attention.

docs/financial/paymentAPI.md

+## Payment API
+
+Historically, one recorded a payment against a contribution by changing its payment status, for example from Pending to Completed. 
+
+It is now best practice to use the Payment.create API call.
+
+Note that paymentprocessor.pay handles the communication with a payment processor to instigate a payment. Similarly, paymentprocessor.refund handles the communication with a payment processor to instigate a refund.
+
+After a contribution has been created, for example using the best practice Order.create API call, use the Payment.create API action to
+
+* record a payment against the contribution - either fully or partially paying the contribution amount
+* record a refund against the contribution
+
+Use the Payment.cancel api to reverse a refunded payment.
+