Tutorial for new users

[chrisbarrett]

We should have a tutorial so that first-time users can learn how to customise spacemacs. We should cover at least the following:

• Basic orientation
  • Running commands
  • Switching buffers
  • Killing buffers
  • Opening files
  • Saving files
  • Using Emacs' help system
• Creating the .spacemacs
• Creating a first configuration layer
• Basic package config with use-package
• Customising key bindings

Any other stuff we should cover?

I think it would be cool if we host the tutorial inside Emacs. We could run the tutorial after startup if ~/.spacemacs doesn't exist.

[tuhdo]

Something I found it could be useful:

• What is a layer?
• How to use helm-spacemacs to explore available layers and look for documentation of a layer from within Spacemacs (new people don't need to look at configuration yet).
• How to activate a layer.

[ghost]

What is a Linux? /s

In all seriousness, this could be very useful for new coders and new Emacs Users / Converts alike.

[idbrii]

I've started a VIMUSERS.md file in aa4cbff that's aimed at filling in chrisbarrett's outline. I don't want to cover any advanced topics like creating config layers since that's for users who are already comfortable with spacemacs.

I'm a hardcore vim user who's trying out spacemacs and this tutorial is mostly stuff that confused or annoyed me.

Hopefully the differences section can eventually be limited to the Differences in defaults.

Eventually, I want to have a "common vim changes" section that covers stuff in tpope/vim-sensible or that's recommended in vim help.

[syl20bnr]

@idbrii I'm impressed by this draft, it is very valuable, not only it will save a lof of time for vim user but it points them into the right directions to use spacemacs effectively right from the beginning.

👍

[xfq]

Something that might be useful:

• What is a micro-state?
• Differences between Vim, Evil, and Spacemacs

[geo7]

Are these now covered by current docs / Vim Users Guide ? @person808 @TheBB

[person808]

VIMUSERS.org has all of this. I think the regular docs have it too.

[StreakyCobra]

This VIMUSERS.org tutorial is indeed very valuable. What I suggest to do:

1. It's a general enough document to not be vim-specific. Adding a paragraph at the beginning explaining that:

   • In the emacs mode the emacs commands are working as usual
   • SPC should be replaced by M-m

   should probably be enough to make it a quick start guide on its own.

2. It should be merged with the actual QUICK_START.org, and keep this name.

3. The resulting document should be:

   • Highlighted in in the top of the README
   • Highlighted on the website
   • Opened on the first start of Spacemacs (i.e. when no .spacemacs/.spacemacs.d)

It's a big – but nice – beginner friendly work ☺️

[TheBB]

You have my blessing. 👍

[CestDiego]

I thing that in the tutorial something about closing windows and moving around should be included :)

[robbyoconnor]

I learned heaps within the past few months

[idbrii]

Two opinions (feel free to ignore them):

This document is more useful if it *is *specific to vim users since they
are an entire class of users separate from anyone else using a vim
emulator. When I started using spacemacs I found the documentation too
verbose and aimed at the general user. I wasn't a general user, I was a vim
power user. VIMUSERS was created to help people in my position to quickly
harness the power of emacs by relating vim metaphors. (The current document
may be broader than I'm describing -- I didn't finish what I started and
someone else picked up the slack.)

Making QUICK_START.org bigger will make it no longer quick. It's probably
better to have two documents: quick start (max 500 words) and bootcamp
(everyone dump what they think every new user needs to know here). That way
the quick start has a hope of being a brief read.

-David

On Sat, Nov 14, 2015 at 11:17 AM, Fabien Dubosson notifications@github.com
wrote:

This VIMUSERS.org tutorial is indeed very valuable. What I suggest to do:

It's a general enough document to not be vim-specific. Adding a
paragraph at the beginning explaining that:

• In the emacs mode the emacs commands are working as usual

  • SPC should be replaced by M-m

  should probably be enough to make it a quick start guide on its own.
  2.

  It should be merged with the actual QUICK_START.org, and keep this
  name.
  3.

  The resulting document should be:

• Highlighted in in the top of the README

  • Highlighted on the website
  • Opened on the first start of Spacemacs (i.e. when no .spacemacs/
    .spacemacs.d)

It's a big – but nice – beginner friendly work [image: ☺️]

—
Reply to this email directly or view it on GitHub
#773 (comment).

[StreakyCobra]

Ok, maybe a short quick start file, as it is now, is needed. But there is a documentation missing between the quick-start and the full documentation. Something explaining the basic concepts of Spacemacs. People are asking for this on Gitter.

The VIMUSERS.org contains vim-oriented comparisons, yes, but its structure is exactly what is needed to introduce Spacemacs briefly. To avoid duplicating documentations, I'm sure this document can be slightly reworded and used for this purpose.

If we omit the Philosophy and Terms sections, there is only 8 references to vim in the whole file. It means the rest of the document will be useful for all users. I'm not saying it should be changed, it is really good as it is now. It should just be renamed to something more general, slightly reworded to explain the reference to vim can be ignored by emacser, and pushed forward to the front-page.

So the point 2) of my previous list can be discussed (but still, I'm not sure the current quick start document is useful at all). Otherwise point 1) and 3) are not going to change anything for vim users, and it will even be better as it will make this document more visible :-)

[JuanCaicedo]

I'm starting out right now, coming from using Sublime Text. If you want I could mention questions I have as I'm learning, as well as solutions I find.

[CestDiego]

@JuanCaicedo that'd be nice

[JuanCaicedo]

I started jotting down my questions in this gist. I'll add answers as I find them, but feel free to comment with answers or additional questions!

[robbyoconnor]

@JuanCaicedo

How to view all buffers

• SPC b b
• or add the ibuffer layer

[gilch]

Also point them to evil tutor and explain what evil/holy/hybrid modes are. Point them to M-x customize.

[backnotprop]

👍

[achikin]

The funny thing is - now there is a section about evil-tutor in the documentation https://github.com/syl20bnr/spacemacs/blob/master/doc/QUICK_START.org , but not a single word about a normal tutor. I do remember there was an emacs tutorial, but I have no idea how to bring it up. Could please someone help?

[xfq]

@achikin Do you mean C-h t (help-with-tutorial)?

[Compro-Prasad]

What I think is that we can provide a tutorial in a sandbox where pressing any key will be interactive. We can start with a blank screen by showing only the minibuffer and ask the user to press any key to continue. Then each UI component will be slowly unwrapped and its use will be printed somewhere either a tooltip or using the minibuffer or the actual buffer. Using hydra in this tutorial looks like a good option. The basic key presses with which-key and getting into the documentation are very much useful too. We will just guide the user till the end. We can provide them to write sample code during the walk-through. If we don't sandbox then it is for sure overwhelming for a new user. There can also be a point where they can pause and use actual spacemacs and resume on demand. Have different checkpoints so that they can jump straight to what they want to know.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Please let us know if this issue is still valid!