diff --git a/src/tactic/arith/degree_shift_tactic.h b/src/tactic/arith/degree_shift_tactic.h
index 9f3f9f09d..cdc4823e2 100644
--- a/src/tactic/arith/degree_shift_tactic.h
+++ b/src/tactic/arith/degree_shift_tactic.h
@@ -5,18 +5,37 @@ Module Name:
 
     degree_shift_tactic.h
 
-Abstract:
-
-    Simple degree shift procedure. 
-    Basic idea: if goal G contains a real variable x, x occurs with degrees
-    d_1, ..., d_k in G, and n = gcd(d_1, ..., d_k) > 1. 
-    Then, replace x^n with a new fresh variable y.
-
 Author:
 
     Leonardo de Moura (leonardo) 2011-12-30.
 
-Revision History:
+Tactic Documentation:
+
+## Tactic degree-shift
+
+### Short Description
+
+The procedure reduces the degrees of variables.
+
+### Long Description
+    
+Basic idea: if goal $G$ contains a real variable $x$, $x$ occurs with degrees
+$d_1, ..., d_k$ in $G$, and $n = \gcd(d_1, ..., d_k) > 1$.
+Then, replace $x^n$ with a new fresh variable $y$.
+
+### Example
+
+```z3
+(declare-const x Real)
+(declare-const y Real)
+(assert (> (+ (* x x x 4) (* x x 3) 0)))
+(assert (= (* x x) (* y y)))
+(apply degree-shift)
+```
+
+### Notes
+
+* supports proofs and cores
 
 --*/
 #pragma once
diff --git a/src/tactic/arith/diff_neq_tactic.cpp b/src/tactic/arith/diff_neq_tactic.cpp
index 4269aff85..59baace10 100644
--- a/src/tactic/arith/diff_neq_tactic.cpp
+++ b/src/tactic/arith/diff_neq_tactic.cpp
@@ -365,7 +365,7 @@ public:
     }
 
     void collect_param_descrs(param_descrs & r) override {
-        r.insert("diff_neq_max_k", CPK_UINT, "(default: 1024) maximum variable upper bound for diff neq solver.");
+        r.insert("diff_neq_max_k", CPK_UINT, "maximum variable upper bound for diff neq solver.", "1024");
     }
 
     void collect_statistics(statistics & st) const override {
diff --git a/src/tactic/arith/diff_neq_tactic.h b/src/tactic/arith/diff_neq_tactic.h
index 2280a5d77..02028c385 100644
--- a/src/tactic/arith/diff_neq_tactic.h
+++ b/src/tactic/arith/diff_neq_tactic.h
@@ -5,19 +5,45 @@ Module Name:
 
     diff_neq_tactic.h
 
-Abstract:
-
-    Solver for integer problems that contains literals of the form
-       k <= x
-       x <= k
-       x - y != k
-    And all variables are bounded.   
-
 Author:
 
     Leonardo de Moura (leonardo) 2012-02-07.
 
-Revision History:
+Tactic Documentation:
+
+## Tactic diff-neq
+
+### Short Description
+
+A specialized solver for integer problems using only constant bounds and differences to constants.
+
+### Long Description
+
+Solver for integer problems that contains literals of the form
+```
+       k <= x
+       x <= k
+       x - y != k
+```
+
+### Example
+
+```z3
+(declare-const x Int)
+(declare-const y Int)
+(assert (<= 0 x))
+(assert (<= x 1))
+(assert (<= 0 y))
+(assert (<= y 1))
+(assert (not (= (+ x (* -1 y)) -1)))
+(assert (not (= (+ x (* -1 y)) 1)))
+(assert (not (= (+ x (* -1 y)) 0)))
+(apply diff-neq)
+```
+
+### Notes
+
+* The tactic works only when the lower bounds are 0 and disequalities use multiplication with -1. Use normalize-bounds to ensure all lower bounds are 0.
 
 --*/
 #pragma once