Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposed style/wording tweaks #783

Open
inexorabletash opened this issue Nov 9, 2024 · 0 comments
Open

Proposed style/wording tweaks #783

inexorabletash opened this issue Nov 9, 2024 · 0 comments

Comments

@inexorabletash
Copy link
Member

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant