Write a style guide for error/user-facing messages

[philpax]

As we have more and more user-facing text (especially in the more "compiler-y" aspects of the runtime and API), I've realised that the text is not very consistent in style, which can be quite jarring to read when you have multiple messages in close proximity.

I'm thinking about writing a style guide and then updating some of the more prominent strings to match that guide.

Here's a first pass at some of the guidelines:

• Use American English. (Sadly, the Americans won the race to standardise technological terms.)
• Messages should start with some consistent casing. Not sure if lower-case or upper-case.
• Objects (packages, components, etc) should be referred to with surrounding backticks. That is, the package `bobcat` does not have a component `is_bobcat`.
• Paths should be referred to with quotation marks surrounding them. (The Rust debug implementation for paths does this automatically.)
• The additional context (as in the anyhow kind) for an error should be a message in itself, not just a fragment. That is, Error while processing single pipeline in "lol.toml", instead of In pipeline "lol.toml".
• In general, try to optimize for easy copy-ability / clicking. If it's a link, you should be able to click it in your terminal without having to manually select it.
• Use logging instead of println within the application (app/ and elsewhere). This is the only one I'm not sure about, but it's what we're currently doing, and it gives us timestamps.

[ten3roberts]

Use logging instead of println within the application (app/ and elsewhere). This is the only one I'm not sure about, but it's what we're currently doing, and it gives us timestamps.

Yes, not entirely sure about that one either. On one hand logging provides a nice UI for what is going on, on another hand logging is intended for process introspection with fields, location etc which is not relevant for user facing status, but rather a background thing you can enable in tangent to the user UI

[ten3roberts]

The CLI apps in rust which use log that I have encountered all feel very raw and low-level facing catering to the technical users more

[pierd]

IMHO logging > println

remembering that everything INFO and above is user facing (DEBUG/TRACE less so)

[pierd]

• Use American English. (Sadly, the Americans won the race to standardise technological terms.)

Agreed 😢 also "standardize"

[philpax]

• Use American English. (Sadly, the Americans won the race to standardise technological terms.)

Agreed 😢 also "standardize"

I did that on purpose 🤣

[philpax]

I'll check out a few other game engines and see if they use logs or raw output. I'm leaning towards logging because I think it's important, in general, to know when something happened and how severe it was - but you probably don't need that for instant-exit commands like new or login, so maybe there's a middle ground here.

Does anyone have any strong feelings about "Error during capacitor frobnication" or "error during capacitor frobnication"? The latter is the Rust style, so I'm leaning towards that.

[ten3roberts]

The diffirences between them, and the reason that Rust uses the lowercase variant is how it is printed at the end. The error messages which rust prints are printed like panicked at: 'error during capacitor frobnification', where a capatalization would not be gramatically correct.

However, our errors will be printed by anyhow and thus be in a bulleted form, where capitalization is considered correct grammar.

I think serde puts this difference quite clearly as they state that your error message will be part of a larger sentence, rather than stand alone.

https://docs.rs/serde/latest/serde/de/trait.Visitor.html#tymethod.expecting