intellij-plugin-v4

intellij-plugin-v4 copied to clipboard

1. I install the plugin, and see syntax highlighting.
2. After couple of days, I discover two tabs at the bottom, named "ANTLR Preview" and "Tool Output". I look at the official plugin page and see some screenshots.
3. I scroll through the screenshots but have no clue how to generate what's shown in them.
4. I import the grammar file using the "File" option, nothing happens.
5. I randomly click on stuff, until I find some ANTLR related options in the context menu when a rule is selected.
6. I select "Test Rule", and that magically creates a parse tree.

Honestly, I didn't install the plugin to play a "guess what it does" game. Please consider making two videos demonstrating:

1. Basic features to get started.
2. Advanced capabilities of this plugin.

Also, the screenshots are probably several years old, and don't match the latest IntelliJ versions.

I agree the documentation part could be improved, but I'm not sure a video would be the best format. There are many features that are kinda hard to find (like running the preview, the profiler, ambiguities viewer etc.). They are mentioned in the readme, but not always explained in detail. Also there's not "getting started" section.

A video requires a certain amount of work, especially if you want it to look nice, and if you want audio comments with it. Also, it's not googleable, and since you are mentioning old screenshots, it will require much more work when you want to "refresh" it.

On the other hand, written docs are more flexible, simpler to maintain, searchable etc. You can easily skip parts you're not interested in. It's also way easier for contributors to submit a PR to improve a static website than to record their own video :)

Two great examples:

• https://www.jetbrains.com/help/idea/discover-intellij-idea.html (although I rarely use it)
• https://jetbrains.org/intellij/sdk/docs/intro/welcome.html (which I often use, the search box on the top left corner is super useful)

I think the current readme could be converted to its own website, categorized and improved especially for newcomers. It could be hosted on antlr.github.io or maybe even www.antlr.org.

WDYT?

Actually what you described in your comment is already detailed in the readme: https://github.com/antlr/intellij-plugin-v4/#live-parse-tree-preview

So I guess taking 5 minutes to read it could have saved you a lot of time.

I guess taking 5 minutes to read it

Read what? The section you referred to is a collection of screenshots, beginning with the following:

I have certainly spent a lot more than 5 minutes with the screenshots. In fact, it took more than 5 minutes to write this ticket. I'm not trying to undermine the content in the README; the point I'm trying to make is that in some distant past, gadgets used to come with 100 page printed manuals. Then they put the manuals on CDs. Now, they simply make "how-to" videos and put them online, because the simplest way to learn is by seeing someone else do it.

I don't think a collaborator on this project would properly appreciate the problem being highlighted here, because they are too close to the product. A beginner or new user would most likely have a different perspective.

The first sentence is literally what you were talking about regarding the preview window:

You can test any rule in the (parser) grammar. Right click on rule in grammar or navigator to "Test ANTLR Rule".

OK, it doesn't say there is a preview window, but it opens automatically when you test a rule.

gadgets used to come with 100 page printed manuals.

I'm confused, do you want detailed written docs or videos?

I'm thinking about making a tour video that could be useful. Personally I prefer written stuff, but I guess a GUI could use a tour video haha.

Hi. Got first video up: https://www.youtube.com/watch?v=JbnjtbPhIX4 Can you take a look @asarkar

And another https://www.youtube.com/watch?v=0A2-BquvxMU