Style guide for written text

[david-christiansen]

There should be a style guide for the documentation, to keep things more consistent, even if it can't be machine checked.

Good points:

• Avoid jargon when possible, link to definitions if possible
• We should standardi(s/z)e on a particular English variant (or at least ask that any given document is self-consistent)
• Capitalize acronyms
• Put command-line tools, programming-language identifiers, and package names in code font
• Annotate fenced code blocks with their language where possible
• Use $ to indicate shell prompts
• etc

Ideally, we can do some of this through CI - I'll look around at Markdown-aware style checkers.

[BinderDavid]

One thing to add here is the way the user should be addressed, which I just noticed when revising an explanation. Should we always write: "If you write a top-level definition and omit the type signature, GHC will emit this warning to tell you that ..." or "If a top-level definition does not have a type signature, GHC warns against the problem that..."

[david-christiansen]

This is a good one. My personal preference is to have text that describes the system, rather than the user, because we don't know the user, but that can also feel a bit distant and formal sometimes. What do you prefer?

[BinderDavid]

I don't have a strong preference, and will follow whatever consistent style we decide on. But I have been researching the design of error messages recently, and there is a nice metastudy on the literature about good error messages: https://dl.acm.org/doi/10.1145/3344429.3372508 Section 8.4 is about research on the tone of error messages. A more anthropomorphized style might be more suitable for novices and younger programmers:

"Lee & Ko [113 ] demonstrate effective use of anthropomorphised error feedback. They argue that it succeeds because novice pro- grammers see programming tools as cold and judgemental and that by personifying the tool programmers can attribute failure to the computer instead of themselves."

But this style of explanations would be inconsistent with the way GHC and the other Haskell tools usually explains errors... So I would probably default to the impersonal style.