spritejs icon indicating copy to clipboard operation
spritejs copied to clipboard

docker, ollama, history, tldr: fix mnemonics

Open swoh816 opened this issue 9 months ago • 3 comments

  • [x] The page(s) are in the correct platform directories: common, linux, osx, windows, sunos, android, etc.
  • [x] The page(s) have at most 8 examples.
  • [ ] The page description(s) have links to documentation or a homepage.
  • [x] The page(s) follow the content guidelines.
  • [x] The PR title conforms to the recommended templates.
  • Version of the command being documented (if known):

swoh816 avatar May 08 '24 23:05 swoh816

Thanks for your contribution, I have some suggestions for this page.

While we support contextual mnemonics in the style guide, it is mostly useful when there are multiple options to highlight or in translations. But IMO, adding mnemonics to descriptions in the history.md file isn't required since the description already implies it, so can you revert the changes to it?

Other suggestions can be found in my review comments.

Thanks for your helpful comments @kbdharun . It is not a problem at all to revert changes in history.md file. Just one clarification question: What do you mean by that mnemonics are useful when there are multiple options to highlight or in translation? Also, isn't it generally helpful to indicate mnemonics in the description, whether or not the description implies the mnemonics? In fact, most of the mnemonics can be inferred by the associated options anyway, such as -r of rm -r for recursive, -f for rm -f for forcefully. But I still thought you should indicate them in the description even if they are obvious from the description or their inference.

swoh816 avatar May 09 '24 17:05 swoh816

Thanks for your helpful comments @kbdharun . It is not a problem at all to revert changes in history.md file. Just one clarification question: What do you mean by that mnemonics are useful when there are multiple options to highlight or in translation? Also, isn't it generally helpful to indicate mnemonics in the description, whether or not the description implies the mnemonics? In fact, most of the mnemonics can be inferred by the associated options anyway, such as -r of rm -r for recursive, -f for rm -f for forcefully. But I still thought you should indicate them in the description even if they are obvious from the description or their inference.

I'm OK if the mnemonic change in history.md is reverted. However, I think they don't hurt (the length of the example description is the same); actually, I think there are some small benefits.

  1. Easier to understand if the example description is quite long or complex.
  2. Visually imediate association between thr mnemonic and the short options.
  3. Makes anyone who proposes a PR and its reviewers to pay attention to the mnemonic, not accidentally:
    • Removing the association between the keyword and the short option
    • Forgetting to use a placholder.
  4. Consitency with other pages with short options.
  5. Avoids case-by-case analyses which can originate more discussions and, IMO, unnecessary, delays for merging PRs (as I said earlier, the client will render it with the same length, after all)

vitorhcl avatar May 09 '24 22:05 vitorhcl

@vitorhcl Thanks for your comments, I agree with you, particularly with regard to 4. I think it's generally a better practice to maintain consistency in the rule, and keeping an objective rule helps in that respect, rather than relying on somewhat subjective matters such as implication, although I understand it's understandable sometimes. @kbdharun @vitorhcl Your input is much appreciated as always ;)

swoh816 avatar May 12 '24 22:05 swoh816