search

JetBrains / jetbrains_guide

JetBrains Guides where Developer Advocacy and the community share ideas.
Other
165 stars 49 forks source link

Make the guide not PyCharm-specific #1

Closed GauthierPLM closed 4 years ago

GauthierPLM commented 5 years ago

A lot of the content of the guide is not specific to Python/PyCharm but applies to all JetBrains IDEs, such as refactoring demo or web-related content. Even if the language used to demonstrate the feature is Python, I think it does not really matters as the features work identically in other languages. In case a topic is specific to a language, tagging system is already here to indicate it.

Therefore, I think it would be very nice if the guide was more general (JetBrains IDE Guide) and advertised as not a PyCharm-only guide. I think it would benefit all products as the lack of easy-to-read help was one of the biggest issues student encounter (got this feedback when I was Campus Ambassador).

Also I think the current structure of the guide is very easy to use and to read (video + text + link for more info), so it would help many people, as it's simpler to consult than the online help of the product.

pauleveritt commented 5 years ago

Thanks a bunch for the feedback. You have the distinction of being Issue Number 1. :)

In December I had a meeting with the other developer advocates about the Guide. We have some ideas about applying the Guide to other products and sharing content. It is still an open question about "JetBrains Guide" vs. "PyCharm/Rider/etc. Guide", as customers usually want something that has their programming language and product name in it.

At the moment we're going slow to see how this experiment works for PyCharm.

GauthierPLM commented 5 years ago

It is still an open question about "JetBrains Guide" vs. "PyCharm/Rider/etc. Guide", as customers usually want something that has their programming language and product name in it.

I agree that having the name of the product is what people will prefer (as they identify themselves more as PyCharm users than JetBrains IDE users for ex), but I think it's better to have another product name in the title but a good help rather than no help. In addition to be campus ambassador, I also do private mentoring for students learning programming, and most of them barely use the features of their IDE (not to mention many of them don't know how to use a basic feature such as debugger or refactoring). The learning curve is something that really needs to be improved in order to help junior developers to be more productive with, and I strongly believe this guide will be a good help.

A solution that would combine both would be to add a switch that allow to select the IDE used. Then, if the tip is available for that specific IDE/language (for example, most IDE have refactoring tips made by their team) it is displayed. If it is not, then a "generic" version (from another IDE) would be shown instead.

pauleveritt commented 5 years ago

What you describe in the end is what I've proposed: a build-time flag that can toggle the name displayed. It won't fix the important cases: code snippets will be in the wrong programming language, videos will have the wrong code and IDE. But some snippets can remain. This is being considered by the other IDE teams.

I'll leave this ticket open though it might be quite a while before action is taking, as we're looking to see if the PyCharm Guide is successful.

pauleveritt commented 5 years ago

Hi @GauthierPLM just to follow up on this, there's a little bit more happening on this, starting in a couple of weeks.

pauleveritt commented 4 years ago

As an FYI, we now have a launched GoLand Guide and two others planned.

We've discussed a strategy for sharing content, but haven't yet found the right approach. We'll obviously have to sort this out later.

GauthierPLM commented 4 years ago

Go to know!

It's not the best play to say this I know but I'd recommend JetBrains to rework the "learn" (or "doc) pages on JetBrains.com. I had issue to find the Go guide and while searching I noticed this:

Meanwhile, guides have a great UI but does cover only few products and miss links to other resources. When I was a student ambassador, this was an issue for students who didn't found easily the help available.

Having a clear page that give a good visual overview of the resources available (blogs, videos, reference help, guides and social media/forums) would help a lot new users to find their way in this. The resources are great, they are just hard to find. It could also be integrated in the IDE directly with a window presenting all the resources (rather than the quite long "help" menu we have now).

pauleveritt commented 4 years ago

cc @dlsniper @maartenba

Thanks @GauthierPLM for the details. You're right in several respects. First, we haven't done much promotion as we were waiting for a change in the YouTube channel for videos. Last week JetBrains made the decision to start doing some per-IDE YouTube channels. This will let me get the videos out of my paul.everitt@jetbrains.com channel.

Second, the jetbrains.com/pycharm/learn pages (and GoLand as well) have had a lot of discussion about how to re-organize them. While they've won't all be exactly the same, they will all be at least a bit more consistent.

Your point about integrated into the IDE is also one that has gained some amount of discussion.

pauleveritt commented 4 years ago

I think I'll close this one. We have 6 total Guides now, so I believe we've covered the idea here. There's more that could be done in some mythical "Guide 3" that has shared content, but we'll consider that future work.