Extend the advice on derivatives.
Extend the tips/tricks section to include more comprehensive
advice on derivatives.
Change-Id: Iba5768055b32a65e36d70e6f4db62eca9b331253
diff --git a/docs/source/tricks.rst b/docs/source/tricks.rst
index c53ba02..2622e23 100644
--- a/docs/source/tricks.rst
+++ b/docs/source/tricks.rst
@@ -4,14 +4,43 @@
Tips, Tricks & FAQs
===================
-A collection of miscellanous tips, tricks and frequently asked
-questions
+A collection of miscellanous tips, tricks and answers to frequently
+asked questions.
-Derivatives
-===========
+1. Use analytical/automatic derivatives when possible.
-The single most important bit of advice for users of Ceres Solver is
-to use analytic/automatic differentiation when you can. It is tempting
-to take the easy way out and use numeric differentiation. This is a
-bad idea. Numeric differentiation is slow, ill-behaved, hard to get
-right and results in poor convergence behaviour.
+ This is the single most important piece of advice we can give to
+ you. It is tempting to take the easy way out and use numeric
+ differentiation. This is a bad idea. Numeric differentiation is
+ slow, ill-behaved, hard to get right, and results in poor
+ convergence behaviour.
+
+ Ceres allows the user to define templated functors which will
+ be automatically differentiated. For most situations this is enough
+ and we recommend using this facility. In some cases the derivatives
+ are simple enough or the performance considerations are such that
+ the overhead of automatic differentiation is too much. In such
+ cases, analytic derivatives are recommended.
+
+ The use of numerical derivatives should be a measure of last
+ resort, where it is simply not possible to write a templated
+ implementation of the cost function.
+
+ In many cases where it is not possible to do analytic or automatic
+ differentiation of the entire cost function. But it is generally
+ the case that it is possible to decompose the cost function into
+ parts that need to be numerically differentiated and parts that can
+ be automatically or analytically differentiated.
+
+ To this end, Ceres has extensive support for mixing analytic,
+ automatic and numeric differentiation. See
+ :class:`NumericDiffFunctor` and :class:`CostFunctionToFunctor`.
+
+
+2. Diagnosing convergence issues.
+
+ TBD
+
+3. Diagnoising performance issues.
+
+ TBD
