3 ms·

Um… are we talking about the same thing? It’s a menu. This is basic computer usage. Mentioning the menu path is just as good as a screenshot (better, in my opin

Um… are we talking about the same thing? It’s a menu. This is basic computer usage. Mentioning the menu path is just as good as a screenshot (better, in my opinion), and takes much less space and requires less maintenance. If you actually need to explain what a menu is and how to use one, the screenshot genuinely won’t help. And when this is intended just as a reminder of what has already been covered, a screenshot is even more inappropriate. I’m not saying there should be nothing there. I’m saying that the screenshot should have been text. I’m genuinely baffled about what you’re actually saying.

samsquire 3y ago
I will try to explain. My learning of TLA+ was ad hoc from reading existing code and just "playing with the TLA+ Toolbox". It's not obvious why a particular menu item, or particular sentence is important. A reference table of menu items is less useful than a walk through of how to use pluscal. I literally had some TLA+ code that wasn't running how I expected then I went to pluscal.htm and then that screenshot made is SO obvious that there was a missing step required in my mental model of how TLA+ works. A beginner to IntellIJ needs to be taught that the "Play button" is what they're looking for, and a screenshot puts that into context. Blender is a complicated piece of software, if you had text based descriptions of that tool - I wonder how useful that would be to understanding where similar functionality is placed. Compared to a screenshot WITH CONTEXT. My case highlights how even what seems like a trivial screenshot can actually help people contextualise something that is basic to you. Do basic features go in context menus, toolbars, or hidden in menus. The text "Go to File -> Translate TLA+ algorithm" would be missed if it was in a big document in the middle, as if it's just a fact. The screenshot says "This is important, pay attention".
- chrismorgan 3y ago
  This would seem entirely adequate to me: > We discussed how to translate the pluscal in Setup, but as a refresher, it’s File → Translate PlusCal Algorithm in the menu (Ctrl+T/⌘T by keyboard). This puts a translation below the comment block: Also, if it’s an easily-missed step and something just mysteriously doesn’t work if you miss it out, that’s not a documentation bug, that’s a design bug. (I’m not familiar with it.)

samsquire 3y ago

I will try to explain. My learning of TLA+ was ad hoc from reading existing code and just "playing with the TLA+ Toolbox". It's not obvious why a particular menu item, or particular sentence is important. A reference table of menu items is less useful than a walk through of how to use pluscal. I literally had some TLA+ code that wasn't running how I expected then I went to pluscal.htm and then that screenshot made is SO obvious that there was a missing step required in my mental model of how TLA+ works. A beginner to IntellIJ needs to be taught that the "Play button" is what they're looking for, and a screenshot puts that into context. Blender is a complicated piece of software, if you had text based descriptions of that tool - I wonder how useful that would be to understanding where similar functionality is placed. Compared to a screenshot WITH CONTEXT. My case highlights how even what seems like a trivial screenshot can actually help people contextualise something that is basic to you. Do basic features go in context menus, toolbars, or hidden in menus. The text "Go to File -> Translate TLA+ algorithm" would be missed if it was in a big document in the middle, as if it's just a fact. The screenshot says "This is important, pay attention".

chrismorgan 3y ago
This would seem entirely adequate to me: > We discussed how to translate the pluscal in Setup, but as a refresher, it’s File → Translate PlusCal Algorithm in the menu (Ctrl+T/⌘T by keyboard). This puts a translation below the comment block: Also, if it’s an easily-missed step and something just mysteriously doesn’t work if you miss it out, that’s not a documentation bug, that’s a design bug. (I’m not familiar with it.)