6 ms·

I think documentation MUST have screenshots. I was recently trying to work out TLA+ in TLA Toolbox and there is there is this screenshot in the documentation o

I think documentation MUST have screenshots. I was recently trying to work out TLA+ in TLA Toolbox and there is there is this screenshot in the documentation on this page on PlusCal: https://www.learntla.com/core/pluscal.html https://www.learntla.com/core/pluscal.html The screenshot about going to File menu and clicking "Translate PlusCal Algorithm" was invaluable! Now I can learn that Ctrl+T is the shortcut to run the translation. EDIT: Before this point I was trying to work out why my code was not updating. I had no idea I had to do this important step! I didn't follow a tutorial, I just used learntla.com and the documentation is spread across multiple pages, so it's not obvious what text is important. Some software is by its nature complicated and hard to understand. Such as IntellIJ or TLA+. If you didn't have any training in IntelliJ, could you work out how modules work in IntelliJ? How gradle interacts with IntelliJ? If you have a personal sideproject, I recommend you take screenshots to document milestones and progress and archive them on GitHub or somewhere. When the code stops working or building then you at least have some artifact that preserves what you did.

Kwpolska 3y ago
This specific screenshot seems unhelpful to me. The text below the screenshot already tells you the keyboard shortcut, it could also say "File > Translate PlusCal Algorithm" and be more accessible.
stephenr 3y ago
> If you didn't have any training in IntelliJ People get trained to use an IDE? I gotta say, I've been using IDEA since 2015, and a language-specific IntelliJ based IDE since 2013, and in 10 years of use it's never occurred to me that someone might need training to use it.
- yread 3y ago
  It's a complex tool with lots of hard to discover features. Training can be more efficient than watching youtubers use it since you can ask questions
  - stephenr 3y ago
    > more efficient than watching youtubers That isn't really saying much. "Watching YouTubers" doesn't really seem like a way to learn how to do something, it seems like a way to waste some time and pretend you're one of the cool kids. I can't be the only person who remembers when people learnt how to use a program by using it?
    - yread 3y ago
      "Using it" is fine for a simple tool. But IDE is a complex beast. You can easily fall into a local optimum without discovering and using the best features. Think using arrow keys to navigate in vim. It works, gets the job done but is far from optimal. You could read the manual but I'm sure you agree that training is a lot more efficient use of your time
- fragmede 3y ago
  I mean you can poke around and read the manual/watch YouTube videos and discover things, or you could just have an expert in the thing interactively teach you how to use the program and its features. It's not about needing training, it's about optimizing time spent learning an advanced tool and all its features.
- samsquire 3y ago
  Did you train yourself? On my first day of work I was given access to SVN and then had to piece together how to run the project. So I was bouncing around IntellIJ and all the various tools to make up a modern development environment. In week-0 of an iteration you might just be spending time to get a development environment working. If you wanted to get something working, did you ask your colleague "how to get company IntelliJ linting configuration to work" or how to set up all the IntelliJ modules or facets. Someone coming in with no experience has to learn: * git * command line * linux * containers * gradle (build runner) * makefiles * java jar files, * pom.xml * javascript bundlers, React/Angular, selenium, frontend testing, storybook * database migrations * IntellIJ' integrations/representations of the above
  - stephenr 3y ago
    I don't use IDEA for Java work, I use it because it's the only IntelliJ platform app that supports "all" languages (or at least all the languages I care about), but sure let's go with your examples above. If you're hiring someone to do java work, who has no experience of jar files, or java build tools, them not being able to use IDEA is the least of your concern. This is like saying "on the first day of work as a carpenter, we send all new hires on an intensive nail-gun training course, because they probably don't know how to use a circular saw, or even what the pointy end of a nail is for" I don't know what schools teach these days, but all the classes I had (one of which, coincidentally enough was java) specifically made us not use an IDE - we had to use a text editor for all practical work. Once you know what you actually need/want to do, using a different tool to achieve it is generally not a complex task. If someone knows how to use a screw driver, they don't need comprehensive training to then use an electric drill/driver to put a screw in. If they don't know how to use a screw driver, giving them a drill/driver to learn, is a fucking terrible idea.
chrismorgan 3y ago
That’s an excellent example of a bad screenshot, something that should have been conveyed as text: File → Translate PlusCal Algorithm (Ctrl+T/⌘T) Later in the page there’s a potentially useful screenshot, https://www.learntla.com/_images/pluscal_run.png https://www.learntla.com/_images/pluscal_run.png. But that first one shouldn’t have been a screenshot: it conveys roughly no value over text (a little value for some people, a negative value for others), and it imposes a distinct maintenance burden.
- samsquire 3y ago
  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.
harywilke 3y ago
The screenshot could be more clear by highlighting 'file' and 'Translate PlusCal Algoritm'. This could be useful in skimming the documentation, but i think this could be a case of where text would be the clearer option.

Kwpolska 3y ago

This specific screenshot seems unhelpful to me. The text below the screenshot already tells you the keyboard shortcut, it could also say "File > Translate PlusCal Algorithm" and be more accessible.

stephenr 3y ago

> If you didn't have any training in IntelliJ People get trained to use an IDE? I gotta say, I've been using IDEA since 2015, and a language-specific IntelliJ based IDE since 2013, and in 10 years of use it's never occurred to me that someone might need training to use it.

yread 3y ago
It's a complex tool with lots of hard to discover features. Training can be more efficient than watching youtubers use it since you can ask questions
- stephenr 3y ago
  > more efficient than watching youtubers That isn't really saying much. "Watching YouTubers" doesn't really seem like a way to learn how to do something, it seems like a way to waste some time and pretend you're one of the cool kids. I can't be the only person who remembers when people learnt how to use a program by using it?
  - yread 3y ago
    "Using it" is fine for a simple tool. But IDE is a complex beast. You can easily fall into a local optimum without discovering and using the best features. Think using arrow keys to navigate in vim. It works, gets the job done but is far from optimal. You could read the manual but I'm sure you agree that training is a lot more efficient use of your time
fragmede 3y ago
I mean you can poke around and read the manual/watch YouTube videos and discover things, or you could just have an expert in the thing interactively teach you how to use the program and its features. It's not about needing training, it's about optimizing time spent learning an advanced tool and all its features.
samsquire 3y ago
Did you train yourself? On my first day of work I was given access to SVN and then had to piece together how to run the project. So I was bouncing around IntellIJ and all the various tools to make up a modern development environment. In week-0 of an iteration you might just be spending time to get a development environment working. If you wanted to get something working, did you ask your colleague "how to get company IntelliJ linting configuration to work" or how to set up all the IntelliJ modules or facets. Someone coming in with no experience has to learn: * git * command line * linux * containers * gradle (build runner) * makefiles * java jar files, * pom.xml * javascript bundlers, React/Angular, selenium, frontend testing, storybook * database migrations * IntellIJ' integrations/representations of the above
- stephenr 3y ago
  I don't use IDEA for Java work, I use it because it's the only IntelliJ platform app that supports "all" languages (or at least all the languages I care about), but sure let's go with your examples above. If you're hiring someone to do java work, who has no experience of jar files, or java build tools, them not being able to use IDEA is the least of your concern. This is like saying "on the first day of work as a carpenter, we send all new hires on an intensive nail-gun training course, because they probably don't know how to use a circular saw, or even what the pointy end of a nail is for" I don't know what schools teach these days, but all the classes I had (one of which, coincidentally enough was java) specifically made us not use an IDE - we had to use a text editor for all practical work. Once you know what you actually need/want to do, using a different tool to achieve it is generally not a complex task. If someone knows how to use a screw driver, they don't need comprehensive training to then use an electric drill/driver to put a screw in. If they don't know how to use a screw driver, giving them a drill/driver to learn, is a fucking terrible idea.

chrismorgan 3y ago

That’s an excellent example of a bad screenshot, something that should have been conveyed as text: File → Translate PlusCal Algorithm (Ctrl+T/⌘T) Later in the page there’s a potentially useful screenshot, https://www.learntla.com/_images/pluscal_run.png https://www.learntla.com/_images/pluscal_run.png. But that first one shouldn’t have been a screenshot: it conveys roughly no value over text (a little value for some people, a negative value for others), and it imposes a distinct maintenance burden.

samsquire 3y ago
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.

harywilke 3y ago

The screenshot could be more clear by highlighting 'file' and 'Translate PlusCal Algoritm'. This could be useful in skimming the documentation, but i think this could be a case of where text would be the clearer option.