explain more about the reason to use slash/star

nedbat · nedbat · commit 750ceb2c9941 · 2024-07-11T16:31:21.000-04:00
diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst
@@ -285,9 +285,14 @@ making false assumptions about the language ("I was surprised by ...").
 Function signatures
 ===================
 
-These are the evolving guidelines for how to include function signatures in the docs:
+These are the evolving guidelines for how to include function signatures in the
+reference guide.  As outlined in :ref:`diataxis`, reference material should
+prioritize precision and completeness.
 
 - If a function accepts positional-only or keyword-only arguments, include the
   slash and the star in the signature as appropriate::
 
    .. function:: some_function(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
+
+  Although the syntax is terse, it is precise about the allowable ways to call
+  the function and is taken from Python itself.
