add subsections

Author: cfbolz

posts/2021/12/error-message-style-guides.txt

@@ -31,13 +31,8 @@ and contain many great points, I recommend reading them directly! In this
 post, I'll try to summarize some common themes or topics that I thought were
 particularly interesting.
 
-Several guides (such as Flix and Flow) point out a 80/20 rule: 80% of the times an error message is
-read, the developer knows that message well and knows exactly what to do. For
-this use case it's important that the message is short. On the other hand, 20%
-of the times this same message will have to be understood by a developer who
-has never seen it before and is confused, and so the message needs to contain
-enough information
-to allow them to find out what is going on.
+Language Use
+------------
 
 Almost all guides stress the need for plain and simple English, as well as
 conciseness and clarity [Flix, Racket, Rust, Flow]. Flow suggests to put coding
@@ -53,6 +48,17 @@ Flow suggests to avoid "compiler speak". For example terms like 'token' and
 be used (eg "name" is better). The Racket guide goes further and has a list of
 allowed technical terms and some prohibited terms.
 
+Structure
+---------
+
+Several guides (such as Flix and Flow) point out a 80/20 rule: 80% of the times an error message is
+read, the developer knows that message well and knows exactly what to do. For
+this use case it's important that the message is short. On the other hand, 20%
+of the times this same message will have to be understood by a developer who
+has never seen it before and is confused, and so the message needs to contain
+enough information
+to allow them to find out what is going on.
+
 The Racket guide proposes to use the following general structure for errors:
 'State the constraint that was violated ("expected a"), followed by what was
 found instead.'
@@ -65,6 +71,9 @@ suggestions altogether because "Students will follow well‐meaning‐but‐wron
 advice uncritically, if only because they have no reason to doubt the
 authoritative voice of the tool."
 
+Formatting and Source Positions
+-------------------------------
+
 The Rust guide suggests to put all identifiers into backticks, Flow formats the error messages using full Markdown.
 
 The Clang, Flow and Rust guides point out the importance of using precise
@@ -73,13 +82,17 @@ compiler information is used in the context of an IDE to show a red squiggly
 underline or some other highlighting. The spans should be as small as possible to point out the source of
 the error [Flow].
 
+Conclusion
+----------
+
 I am quite impressed how advanced and well-thought out the approaches are. I wonder whether it would makes sense for
 Python to adopt a (probably minimal, to get started) subset of these ideas as guidelines for its own errors.
 
 .. _`full list`:
 
 Sources
 -------
+
 * Rust: https://rustc-dev-guide.rust-lang.org/diagnostics.html
 
 * Clang: https://clang.llvm.org/diagnostics.html