diff --git a/src/calc_integrate.jl b/src/calc_integrate.jl
index 2851e5a..34e6ed8 100644
--- a/src/calc_integrate.jl
+++ b/src/calc_integrate.jl
@@ -276,7 +276,8 @@ will be given a keyword argument `analytic::Bool`, if `analytic` is
 `true` then the output has to be non-finite (typically `Acb(NaN)`) if
 `f` is not holomorphic on the whole input ball.
 
-!!! Note: It's users responsibility to verify holomorphicity of `f`.
+!!! note
+    Users are responsible for verifying holomorphicity of `f`.
 
 Parameters:
  * `take_prec` if true then `f` will be given the keyword argument
@@ -289,9 +290,10 @@ Parameters:
  * `opts` a `C_NULL` (using the default options), or an instance of
    `acb_calc_integrate_opt_struct` controlling the algorithmic aspects of integration.
 
-!!! Note: `integrate` does not guarantee to satisfy provided
-    tolerances. But the result is guaranteed to be contained in the
-    resulting ball.
+!!! note
+    `integrate` does not guarantee to satisfy provided
+    tolerances. But the integration result is guaranteed to be contained
+    in the returned ball.
 
 For more information please consider arblib documentation and the
 paper
diff --git a/src/poly.jl b/src/poly.jl
index d8dce65..c2d54ca 100644
--- a/src/poly.jl
+++ b/src/poly.jl
@@ -83,9 +83,10 @@ Similar to `p[i]` but instead of an `Arb` or `Acb` returns an `ArbRef`
 or `AcbRef` which shares the memory with the `i`-th coefficient of
 `p`.
 
-!!! Note: For reading coefficients this is always safe, but if the
+!!! note
+    Using `ref` for reading coefficients is always safe, but if the
     coefficient is mutated then care has to be taken. See the comment
-    further down for how to handle this.
+    further down for how to handle mutation.
 
 It only allows accessing coefficients that are allocated. For
 `ArbPoly` and `AcbPoly` this is typically all coefficients up to the