A Get Started introduction to emacs

[Moakt Temporary Email]

Hi Eli, Björn, and everyone,



I wrote a quick “Getting Started” introduction to emacs, and I thought of 
writing this small guide (to be modified as needed), that can be used:
- to discuss and correct the introduction.
- as a guideline:
  + if the introduction needs to be changed later on.
  + or if someone wants to re-write it in a different way.



Links to images:

1. The modified *GNU Emacs* startup buffer:
https://jpcdn.it/img/41b5d9a27f577dac1bf492b5d5964fb1.png

2. Getting Started:
https://jpcdn.it/img/a331fa46589f47ee5b105dadf9ae01c7.png

3. What Is Next:
(Please ignore the parts that are irrelevant, they should be replaced to point 
to the actual customization interface instead)
https://jpcdn.it/img/bd92dcb25729febfdcb5c1bbc71029e7.png





The HTML markup of the 3 images can be found here:
https://lists.gnu.org/archive/html/emacs-devel/2024-10/msg00245.html.




Why this introduction:

1. emacs has some special terminology and concepts, that new user should know, 
to be able to start using emacs.


2. I proposed a new interface to customize emacs, and user should know some 
basic emacs terms (window, frame, etc.) to be able to use some options 
immediately (though, this apply to the current customization interface too).

Of course, there will still be a lot of options, that new users would not be 
able to understand and use immediately (even after reading this introduction).


3. user needs to understand the terms that he will find everywhere: (not only 
in the customization interface): in blogs, manuals, tutorial, documentations, 
menubar, etc).


4. The actual tutorial, is too long for users, and it contains many things that 
are not really needed to use emacs (keybindings, etc.), which might discourage 
new users.
(This intro is not a replacement for the tutorial, it is simply a very quick 
and lightweight introduction to emacs that enumerate the very essentials)


5. When a new user opens emacs for the first time (*GNU Emacs* buffer), he does 
not really know what to do next.  Hesitating between the tutorial, the manual, 
click on the other links, etc.  This intro will be added to *GNU Emacs*, in a 
way (see image 1), to guide the user from the first time he open emacs, until 
he is comfortable, and feels he can do something useful in emacs (see image 2).
Then it will guide him to:
- the tutorial
- the manual
- and of course to the customization interface (as user would normally need to 
customize emacs at this point, try different themes, add tabs, etc.). (see 
image 3)


In other terms, from the moment user opens emacs for the first time, there no 
need to stop and think and make decisions, etc.  He will just follow the flow 
in a very gradual and smooth way, until he is comfortable enough to perform 
some tasks on his own, without really realizing the time spent, as he is trying 
different actions and discovering multiple things in a very easy and 
interactive way (for example clicking on buttons, if anyone has more ideas, 
they are welcome).





What this introduction should and shouldn’t:

The introduction should be as short as possible.

The introduction should use the most beginner-friendly terms whenever possible, 
while not changing/diverging from emacs terminology (for example using 
command’s input, instead of commands arguments, etc).

It should introduce user to the “minimal” emacs terminology and concepts that 
are needed to start using emacs, anything that is not really needed to start 
using emacs, should not be added.

I would say it in other words, because it is important to stress on it. The 
minimal emacs terminology and concepts, are the ones, user needs to know, after 
which he can use/discover/read everything else on his own. (gradually one thing 
at a time as needed)

If someone hesitate to know if something should be added to the introduction or 
not, he just need to ask himself the following question: “does user really need 
to know about this thing to start using emacs, or he can learn/know about it 
later when/if he needs to ?”

As an example, no need to describe what is the minibuffer or keybindings, in 
the introduction.  They are not really needed to start using emacs, and can be 
checked later by the user when needed (though they can be mentioned _very_ 
briefly).  User can rely on the menubar and toolbar as a starting point, which 
is totally fine (that is why these are here in the first place).





What are these minimal emacs terminology and concepts:
(Please feel free to correct the list below if needed)


* what is a command (the central/important interaction point with emacs)
  - where to find commands (menubar, toolbar)
  - how/where to find the documentation for a command
    (so user can read about other commands)
  - how/where to provide command inputs (echo area)
  - how/where to wait for a feedback (echo area)
  - how to cancel a command (C-g)
    We can _briefly_ mention that this is called a “keybinding”, because it 
binds the C-g key to (run) a command, that will cancel the current running 
command.  And that all other commands are bound to some keys by default in the 
same way.
  

* what is a frame window, buffer, point
  - what a window having a focus means, and how to know that (blinking point)
  - closing a window will not close the buffer
  - closing a buffer will not close the window
  - etc.

* what is the *Messages* buffer
  - how to open it (easiest way is to click in the echo area)

* what is the *Errors* buffer
  - how to open it
    (normally it shows up automatically, but in case user wants to reopened it)
  - what to do in case of errors.

* what is the modeline
  - what are the items it shows.
    no need to give a lot of details about what is a major mode, and minor 
modes (user can read details about them later when needed)

* about the introduction itself
  - how to access it (if user accidentally closed it, or needs to re-read it 
later on)

* tell the user briefly about customizing emacs (see image 3)
  - an overview of what he can customize.
  - how to access the interface to customize emacs.
  - where the customization file is located.
  - etc.



User would do some exercises, to better understand these concepts (open/close a 
window, open/close a file, open/close a documentation, etc.), and repeat them 
as much as needed.  User will also normally tries to open other documentations, 
 and to execute other commands from the menubar/toolbar, etc.

I already included all the above mentioned points and exercises in the 
introduction I proposed. (see image 2 and 3)


After less than 5min read, and trying some (useful) exercises, user will be 
able to start using/discovering the rest, all by himself, one thing at a time, 
and when needed, like any other software.


Having a single “Get Started” link, in the *GNU Emacs* buffer (see image 1.), 
where user can click, to guide him, from the moment he opens emacs, until he is 
comfortable, is better than, showing user many different links to chose from, 
and which are long read and discouraging user from carrying on his use of emacs.


IMHO, this little improvement, can have big impact on new users.

I personally, opened emacs multiple times in the past, and each time I ended up 
closing it in less than 1-3 minutes. (which is totally regrettable)

If this intro was in emacs, I would have used emacs a very long time ago, when 
I opened it for the first time. (of course with a better customization 
interface than the actual one, that is why I am also proposing a new 
customization interface).

Without david wilson’s videos, which I saw by chance, I wouldn’t be using emacs 
today.

Having something powerful like emacs, is not enough, if no (at least little) 
effort is spent in making it more accessible for everyone to discover and try.

I hope, sharing my experience, and proposing this introduction, would 
contribute making emacs better.


Please let me know what do you need from my side, so this introduction can be 
added to emacs.  And if you need me to clarify other points I forgot to mention.


I am willing to spend more time, if you want me to write the missing parts, but 
I really prefer if someone knows emacs better than me, to review it and give me 
some feedback.


If someone wants to re-write the whole or a part of the introduction in another 
way, I don’t mind at all.  I am proposing the idea, not really the text, but if 
you find that the text is good enough, I am willing to spend more time to 
finish it.
(I wrote the text back then, as a skeleton, to show you the idea I had in mind, 
and in the same time, to have something concrete to discuss)




Thank you for your time and congratulations for the new release !