Hacker News Reader

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.

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

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

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.

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.

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

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

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

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.

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

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

> 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?

"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

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.

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

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.