3 ms·

When you're learning something for the first time, it can be hard to know what mental model you need to have to be effective with the tool. Some documentation

When you're learning something for the first time, it can be hard to know what mental model you need to have to be effective with the tool. Some documentation is reference material. With reference material you might navigate the reference material in a particular traversal to get what you need to do what you want. How do I know some fact is important in reference material? The documentation for Git, Emacs or GCC is large and it is not immediately obvious what information is important, yet. But at the beginning of your journey, you need to be taught a "flow" an expected pattern of operation to build up the right mental model of how an average session with the tool works. For programming this might be the edit file, compile, run, debug loop, or TDD or IntelliJ's build and deploy. Or a CI system commit, push, deploy, promote cycle. Or kubernetes kubectl edit, apply. I opened the "dining philosophers TLA+" example and ran it - this seemed to be an affordance of the TLA+ Toolbox GUI which was straightforward to understand. But then I tried to use the tool with my own. I interpreted the existing code of the dining philosophers and tried to make my own ringbuffer model. It took me a while to realise that some of the code in the dining philosophers code was generated from another section. It took me a while that I needed to update this screen to put in the following details that I have filled in on the screenshot: https://github.com/samsquire/assembly/blob/main/screenshots/modeloverview.png https://github.com/samsquire/assembly/blob/main/screenshots/... You have to put your entrypoint in the "temporal formula" and then put your model arguments on the right hand side. I was able to piece together the operation of this tool by piecing together various reference details together, it wasn't until I saw that screenshot I referenced in my OP that I realised I needed to do that step to get the PlusCal code to update the TLC code that follows it. I was wondering why it didn't work until I saw that screenshot.

chrismorgan 3y ago
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.)
PeterisP 3y ago
I think the discussion is caused by different implicit understanding of what "documentation" means. Different types of documentation have different, conflicting needs; an amazing reference document is a horrible tutorial and an amazing tutorial is horrible for reference purposes. So you shouldn't try to make your reference material be useful as a tutorial, that way lies madness, make a separate document if you need one. This is an interesting overview of these concepts - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/ https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

chrismorgan 3y ago

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.)

PeterisP 3y ago

I think the discussion is caused by different implicit understanding of what "documentation" means. Different types of documentation have different, conflicting needs; an amazing reference document is a horrible tutorial and an amazing tutorial is horrible for reference purposes. So you shouldn't try to make your reference material be useful as a tutorial, that way lies madness, make a separate document if you need one. This is an interesting overview of these concepts - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/ https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...