Skip to content

Proposed style/wording tweaks #783

@inexorabletash

Description

@inexorabletash

I'd like preliminary feedback on some proposed wording/styling/linking changes:

  • When referring to arguments and options in prose, avoid the wordier the *foo* argument or the *bar* value forms; just use the name alone.
  • When referencing an argument in prose steps, link to it rather than just using formatted text e.g. {{MLGraphBuilder/split(input, splits*, options)/splits}} rather than *splits*.
  • Avoid <var>v</var> or |v| outside of algorithms; Bikeshed interprets these as global variables which can mask errors. Just use *v*.
    • Format each term separately; that is, *splits*[*i*] not *splits[i]*.
  • Dictionary members should be linked to, both in algorithms and in other text. e.g. |options|.{{MLOptionsDict/member}} (in the steps for an algorithm) or *options*.{{MLOptionsDict/member}} (outside an algorithm).
    • And to simplify even further: outside algorithms, drop the *options*. entirely and just link to the member.

Thoughts?

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions