[RFC] Elpy video tutorial

[sten0]

@galaunay, continuing from #1596

I will try to think about what we can do documentation-wise for new Emacs users. Honestly, the best would be a screencast or youtube tutorial, but that's a bit outside of my skills.

I've prepared a couple of minor tech-support videos (with voice-over) so could help with that side of things. Keyboard shortcuts could be shown using either block comments, or as a fancy overlay (shouldn't be too hard to figure out). The parts of the tutorial I would need help with are:

0. Do installation instruction need to be part of this tutorial?
1. What features to showcase, and in what order?
2. Common work-flow[s] that a someone from a Python background would value. [1] tends to be super boring unless it's framed right using [2]. I'm guessing these could be organised in broad categories like: a) Starting a new project b) Debugging c) Suggestions?
3. Elpy depends on find-file-in-project, so should the tutorial also showcase a bit of Ivy, since all users will have it installed? Yeah, that's "opinionated software/documentation", but I suspect the target audience for this video will tend to be new users. With the voice-over explanation I imagine Helm users will understand what's happening and think something along the lines of "Helm can do this better", and maybe even make their own video ;-)
4. In addition to a demo of the "IDE Features", I wonder if users coming from other IDEs would appreciate a demo of addons like neotree (file hierarchy tree browsing as a vertical side-pane) and imenu-list (class and function hyperlinked list as a side-pane)?

If it's on Youtube then we can link to different operations/categories in the description, that jump to the corresponding timestamp of the video. At this point the scope of an "intro to Emacs via Elpy" feels too big, so a short series of focused videos might be better... Definitely shouldn't be comprehensive of course. As I see it, the objectives are a) Provide concessions for non-Emacs users (so they can understand what they're seeing). b) Give viewers a taste of the magic, at just the right speed...a lot of tech demos are overwhelming and incomprehensible to non-insiders.

P.S. I'm curious if a "Communications"-type project will be fun :-)

[galaunay]

I've prepared a couple of minor tech-support videos (with voice-over) so could help with that side of things.

Nice, that would be fantastic. We are planning a bit of restructuration for the documentation in #1606. That, with a set of tutorial, could give a brand new face to Elpy !

0. Do installation instruction need to be part of this tutorial?

I think that would be useful, maybe coupled to a demonstration of the features detailed in the quickstart to get people started ?

1 What features to showcase, and in what order? 2 Common work-flow[s] that a someone from a Python background would value. [1] tends to be super boring unless it's framed right using [2].

That's a very good point. If we could find common work-flows or/and case studies that cover Elpy's features, that would be great.

My attempt to complete your list:

• Starting a new project (could cover virtualenv as well)
• Debugging
• Profiling (could cover code navigation to find and fix a potential bottleneck ?)
• Working Interactively (could cover the shell integration, evaluating code fragments and shell feedback)

There is a few things that imho deserve to be highlighted but that are not enough by themselves to make a screencast. I am not sure yet what to do with them...

• Completion
• Documentation access (autodoc, eldoc, documentation display)
• Code navigation with xref
• Django support
• Testing

3 Elpy depends on find-file-in-project, so should the tutorial also showcase a bit of Ivy, since all users will have it installed?

Were you thinking about specific ivy features ? If think there is a bunch of packages that are very useful in combination with Elpy. I was thinking in particular to: better project management with projectile, semantic navigation (counsel-semantic or helm-semantic-or-imenu), advanced buffer searching (swiper or helm-swoop), remote editing (tramp) and git (magit). Maybe we could plan a video to give an overview of the possibilities offered by those packages (ivy included) ?

4 In addition to a demo of the "IDE Features", I wonder if users coming from other IDEs would appreciate a demo of addons like neotree (file hierarchy tree browsing as a vertical side-pane) and imenu-list (class and function hyperlinked list as a side-pane)?

Having something that look more like a traditional IDE before diving into Emacs realms could indeed be more appealing to people (or at least scare them a bit less :)).

At this point the scope of an "intro to Emacs via Elpy" feels too big, so a short series of focused videos might be better...

I couldn't agree more. I have watched some of Mike Zamansky Using Emacs videos. I found very convenient to be able to pick the subject I was interested in. (I am also generally afraid by long videos...)

If we could come with a general plan for this it would be a great first step. It may be useful to have an idea of the quantity of work involved :)

[sten0]

Sorry for forgetting about this all summer! Please feel free to ping me if it seems like I'm taking too long for something. BTW, I found that someone has already released some Elpy videos: https://www.youtube.com/watch?v=0kuCeS-mfyc https://www.youtube.com/watch?v=mflvdXKyA_g

[galaunay]

I wonder why I didn't found those videos before. It is a good start to catch people's attention.

We just need a brand new, updated version of this :).

[lljr]

Hi, I'm interested in helping out with a video series explaining Django and Elpy usage. I briefly mentioned the idea in #1669.

Before getting started, I think if we we're to create a video series it would be good to brand Elpy. As of right now, there are no recognizable logo, image, slogan that associate the project with a catchy brand. Sure, there is a project name "Elpy" but, if we were to make videos, we should keep a consistent image/brand throughout... Don't you think?

By "brand", I specifically mean a logo that can be placed together with the video (YouTube, I'm assuming) playlist. Perhaps even a project slogan/subtitle e.g. "Less typing more programming." (I know it's a bit, meh, but it's the first thing that came to mind).

Developing a brand requires thoughtful work -- probably we should stablish a process in which Elpy users could vote on a submitted logo design(?). Perhaps we may start a contest and allow for logo submissions: choosing a winner for a logo that obtains the most votes.

This is just an idea and may cause more trouble than may prove helpful -- please let me know your thoughts!

[galaunay]

Hi,

A logo would be very nice. Something blending Emacs and Python logos maybe ?

I like the idea of trying to engage users in the design, we just need to find a way to reach them. I know there is people using Emacs that are active on reddit. We could ask emacslife or Sasha chua to diffuse the information as well. The first round would be just asking users to send proposal (which will be simple), we can figure out the voting process later.

Regarding the videos, thanks for offering to help for the Django ones. I have no expertise in making videos, but I can help to structure the content. I will try to make the first draft of a plan so we can move forward.

I have never really used Django, do you have ideas of particular things that we should promote ?