-
Notifications
You must be signed in to change notification settings - Fork 715
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a tutorial like vimtutor
#1122
Comments
That one would be very nice, but I dont think I am the best person to write that, as I think I am a bit too familiar with Kakoune to see how to teach it to new comers. Any volunteer ? |
And I'm on the opposite end of the spectrum: I'd like something like this to help me learn Kakoune. :) |
Here are the various topics from the original vimtutor, this could be a starting point. I guess the first step is to identify the relevant ones, the ones that do not directly apply to kakoune philosophy and add missing concepts.
|
I proposed a small
|
Nice job lisael, thanks! I would add two more chapters after the one dedicated to Multiple Selections. One about the How do you want to proceed for the writting? Should we use the wiki as a temporary place to conbribute drafts ? When good enough you could then include these chapters to as proper asciidoc files to your https://github.com/mawww/kakoune/pull/1144/files PR, and then we could remove them from the wiki. |
Just one thing guys, please dont base that work directly on the vimtutor contents. Dont go read and convert part of the vimtutor to make the Kakoune tutorial, as doing that would make Kakoune's tutorial a derived work of Vim's, preventing us from releasing it under the UNLICENSE. Thanks a lot for taking a look at this, its been missing for far too long. |
@Delapouite: I like the wiki idea, that saves me the burden of managing PRs on my branch. Let's do this. @mawww: yes, I noticed the license issue here: https://github.com/mawww/kakoune/pull/1144/files#diff-a6485e2b20682946e757ea94b4b951f2R10 . If it's not enough, as you seem to think, rewording these sections is far easier than trying to figure out if it's legal or not. We'll re-word them. |
I don't like the "tutor" thing, the interactivity has always been used as an excuse to copy what
That's why, a month ago, I started writing a document that I call a trampoline. I'm assuming that users who want to learn how to use the editor are actually trying to write a small project, and learn on the fly how to do the things they want. With that in mind, the trampoline describes the basics of editing primitives in the editor in small paragraphs, clearly shows what keys are used in them on the side, and can be refered to easily by keeping it open in a pager on the side. But more importantly, it doesn't try to be exhaustive and explain every single primitive implemented by the editor, as that's the documentation's job. The second section about advanced primitives is being written, but in the mean time here is my first draft:
|
@lenormf maybe your point against the tutor thing is true for some user, but there are still users, like @nathanl, who expect something like that. Most Vim users will, and they will learn the concepts easily. That said, either the tutor and trampoline are light enough to be included in the distribution, if it's clearly advertised, these are two options to learn Kakoune. I've already thought about building a project in an advanced part of the tutorial, showing the code of the tutorial itself, which is simple and uses a few core concepts (mappings, custom commands, options, %sh{}...). I also wanted the tutorial to emphasis on the extensibility of Kakoune, and that Kakoune tries to ease the integration with external tools. |
Actually the original issue mentions something that helps new users understand how the editor works, the fact that it was called I think the interactive tutor should get it's own repository in a |
I found Vim tutor boring, but I like @lenormf’s trampoline. |
github may be willing to give back this sleeping account: https://github.com/kakoune |
It doesn't matter what the name is, it could be |
I think the tutorial approach makes sense, especially for users not familiar with modal text editors. Guiding new users progressively, introducing concepts/features along with small exercises seems like the traditional method we use to teach almost anything, I think its a pretty good default. As a feature focused on new users, I'd argue it should be bundled with Kakoune, having a @lenormf approach is pretty different, and seems tailored towards a different way of learning a tool. I think it would actually be a good alternative to the tutorial, especially for people already familiar with Vim. So I'd be okay to merge both as they serve different purposes, in a sense @lenormf's version is a in depth cheatsheet for Kakoune. @lisael We cannot just reword Vim's tutorial, it needs to be written from scratch, else its a derivative work from Vim and we have to license it separately. I'd like to avoid introducing pieces with different licenses in the main repo, except in |
@lenormf the trampoline is exactly what i'm looking for! any progress on the advance primitives section? |
@RandomLetter none, I will create a PR if I ever finish the document. |
I actually found the vim tutor helpful, this trampoline idea seems to tell you the basic concepts but I like to have a playground to test stuff on. |
The playground is just using the editor on a source file. |
follow up on the trampoline: https://github.com/mawww/kakoune/blob/master/contrib/TRAMPOLINE |
Really like @lenormf’s work on trampoline. |
I think that the blog post Everyone Who Tried to Convince Me to use Vim was Wrong [0] gives a valuable perspective for us. Maybe the tutorial should focus on just making in easy and simple for current users of other text editors and IDEs to adapt Kakoune into their daily workflows without make an significant impact on their productivity? I don't think that you have to use Most people don't want to make an initial huge investment into something there they already have a tool that fulfills its purpose. But if they fell comfortable with Kakoune they'll sooner or later begin to explore its capabilities. [0] https://yehudakatz.com/2010/07/29/everyone-who-tried-to-convince-me-to-use-vim-was-wrong/ |
I don't know where we are at concerning the dynamic tutorial but I would like to add my two cents. As much as I like the trampoline, I'd like to defend the fact that having a tutorial with a playground is also good to have. What I want to express is that the trampoline way might be the best way for some and the "tutor" way best for others and therefore we shouldn't choose one over the other. |
We need Vimcasts for Kakoune. ^^ |
I thought append lists for Keys: |
Echoing Sweenu, it should be 100% painless to direct people to a place they can onboard. Comments like,
Demonstrate a lack of understanding of first-exposure UX. If you open up kakoune, first it doesn't show you an empty buffer. What's more, people with some vim exposure are going to be a large part of kakoune's early user base—the first thing many of us are going to look for is a vimtutor equivalent. |
Thank you for writing Trampouine. Reference material has a place, surely, and Trampoline is great for that. However, I kindly request that all reference to vimtutor should be removed from the Trampoline material (just do a websearch for "Kakoune tutor" to see what I mean). This affects google searches and makes finding quick start material more difficult. Trampoline fulfills a very different role and is not suited to those who are trying to commit the basics to muscle memory. It certainly isn't suited to those new to vim-like text editing. When I finished Trampoline, I was still was not comfortable using Kakoune. By contrast, when I first started using vim several years ago, after going through vimtutor a few times, the basics of vim were part of muscle memory and I was quite comfortable to begin using vim. This result is supported by pedagogy research: hands-on experience trumps reading a feature list. FWIW: I am currently going through vimtutor USING kakoune. That is the state of Kakoune learning material. I may write such a tutor once I have a better handle on kakoune. I'll make sure to not pull directly from vimtutor to avoid license issues. I see @lisael is making something, which looks wonderful, but seems much more complex and specialized than what is necessary to get folks up and running. |
There’s no reference to any “tutors” in The wiki was recently updated to link to a third party “tutor”, maybe that will help: https://git.sr.ht/~voroskoi/tutor.kak |
I couldn't get this tutor to work. Perhaps it's user error, perhaps not - there aren't any instructions. If it doesn't work, the wiki should probably remove its listing. |
hey @mawww I think it would be better if you append these in the comments near the top, this top-second comment of urs for example: #1122 (comment) |
What is the status of the kakoune tutorial? Haven't see any activities in a while? |
As mentioned in #249
The text was updated successfully, but these errors were encountered: