The specification uses text quotes and markdown quotes interchangably

[constantinpape]

Currently, in the spec text quotes "some_name" and markdown quoutes some_name are used interchangeably; for example sometimes "mutliscales" is used, sometimes multiscales. It would be nice to be more stringent about this and add a recommendation which quotes to use.

[joshmoore]

Agreed. Sounds like a "style-guide" section. There is likely something within bikeshed itself, e.g. https://tabatkins.github.io/bikeshed/#dfn-types but I don't know if if it's use will be too verbose.

Failing finding a proper markup, I think I'd err on the side of markdown quotes to define class/object-style information.

see also: https://cheatography.com/apowers313/cheat-sheets/bikeshed/

[joshmoore]

I think I'd err on the side of markdown quotes to define class/object-style information

Ah, I think I see what I was (at least sometimes) trying to get across: in some cases it's referring to the json-key instead of the concept. Perhaps that's too confusing to get across and we should just consistently refer to either the type or the json item.

[lubianat]

@jo-mueller noticed this inconsistency in rfc-5 too and filed #423

My 2c is that it may be okay to recommend using markdown quotes whenever possible when referring to fields just to keep things consistent.

Maybe we can add a "Style notes" section on, say https://ngff.openmicroscopy.org/contributing/index.html with bullet points like:

• When referring to fields in the metadata, use markdown quotes (e.g. ome) whenever possible
• (etc)

[jo-mueller]

@lubianat I started writing a contribution guide with some styling hints over at the ngff-spec repo. With #410 merged, maybe we could move this bit upstream into the ngff repo as well. Feedback from the doc team about this part:

While hints on formatting things are important and welcome, we should make sure that the contribution pages are encouraging in the sense that people feel confident about being able to contribute.

[jo-mueller]

Sent a PR to fix :)