When to use back quotes? about icerpc-docs

[ReeceHumphreys]

It is primarily a rendering issue since we put all backquoted text inside these mini-code rectangles. This doesn't leave much space when you have multiple lines with backquotes on top of each other. We could get rid of the rectangles or increase the line height. Either of those would help with readability.

I'll take a look into what other people do for their docs.

[bentoi]

I added back quotes for port numbers to be consistent with the use of <c> in our C# API documentation. I agree it's not a good idea as it's less readable.

I also added back quotes for few C# type names. I would always use back quotes for API type names or language keywords.

In #33, for text such as "on the Compress interceptor, and then finally the Compress interceptor", instead of adding backquotes to Compress (a type that doesn't exist in our C# API), I've changed Compress to compress. I would not use the PascalCase naming convention here since we aren't referring to a C# API.

One remaining debatable use of back quote is in this text: "An invoker implementation can call invoke on another invoker, which itself calls invoke on another invoker, etc.;". We use back quotes for "invoke" which isn't really a method name that exists. And we don't use InvokeAsync for a good reason, our documentation shouldn't be tied to a specific language mapping. Should we keep the back quote for "invoke"? I think I would drop them or rephrase the sentence to not refer to a method.

[externl]

"An invoker implementation can call invoke on another invoker, which itself calls invoke on another invoker, etc.;"

I think "calls invoke on another invoker" sounds odd. I would say that it just "calls on another invoker"

We could write:

"An invoker implementation can call on another invoker, which itself can call on another invoker, etc.;

[ReeceHumphreys]

Just for note, I committed a minor tweak to the css that should make backquoted text more readable: 4c14206