Re: Emacs Newbie Info Pages

[Summer Emacs <summeremacs@summerstar.me>]

[-- Attachment #1: Type: text/plain, Size: 5552 bytes --]

> On Sep 17, 2024, at 15:31, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Summer Emacs <summeremacs@summerstar.me>
>> Date: Tue, 17 Sep 2024 12:58:21 +0200
>> Cc: Suhail Singh <suhailsingh247@gmail.com>, corwin@bru.st, emacs-devel@gnu.org
>> 
>>> How does this proposed Info manual compare with the C-h t Emacs
>>> tutorial?  If they are doing different jobs, how do they differ?
>> 
>> Good questions! Thank you.
>> 
>> 1) My proposal is for new people to have a landing set of pages to click through, explaining things in a clear and easy way for them to understand without the instant introduction of concepts which are alien to them. I think the help files are a great thing, but they are overwhelming for new people. I know this because I’ve shown it to people in my circles who don’t know much of anything about how to use a computer, but still use applications such as Word or Pages to type up things for work/classes. They couldn’t understand the first thing about the help pages.
> 
> I think Richard asked about the difference between what you propose
> and the existing Emacs tutorial (which can be read by typing "C-h t").
> The tutorial is not what you call "help files", and is written in a
> different style and with different goals in mind.
> 
> Or are you saying that the tutorial is also overwhelming, in
> particular due to introducing too many alien concepts?  If so, that
> might be worth a separate discussion, because the tutorial is not
> supposed to be hard to read and understand.
> 

I did mention the tutorial but I said I think it’s fantastic. I was speaking about the other help files in general. Such as clicking on the “Emacs guided tour” - it’s very non-newbie friendly. It’s a great resource but I think we need something better for brand new users who don’t have a coding background.

The first lines in the manual are:
The GNU Emacs Manual calls Emacs the extensible, customizable, self-documenting real-time
display editor, but this description tells beginners little about what Emacs is capable of.
To give you an idea, here is a sampling of the things you can do with Emacs:

Beyond just being able to edit plain text files, Emacs includes special features to help
you write in many different human languages and programming/markup languages:

Now, that’s not too bad (except most people have no idea what extensible means). The second sentence talks about programming/markup languages: most people will think it’s just for programmers. You don’t open up another text editor and it starts talking about programming in the second line. This is not a problem if the person is good with computers and knows a little bit of programming, but that doesn’t describe most people.

The third line is the following:

…as well as tools for compiling, running, and testing programs. Emacs integrates with
GDB to provide an IDE (M-x gdb):

This is completely gobbledygook to most people. My survey results with non-devs:
(Compiling?)
(Running?)
(GDB - fergetabboudit)
(IDE - what?)
(M-x gdb) what’s an M-x?

Again: Great for programmers - they’ll get it, even if they’re completely new to Emacs. They’ll figure it out. Non-programmers? Not so much.

Fourth line:

Emacs can compare two files and highlight their differences (M-x ediff):

Interesting. Most people don’t worry about that as much, however (even if it’s super useful even in non-programming uses). But at the start? Confusing.

Next line:

Emacs is a file manager (M-x dired):

Most people, who actually use file managers, don’t know what a file manager is. I’m a huge, huge, advocate for dired and think that it’s the best thing since sliced bread. In fact, I use it hundreds of times a day now. But throwing that in my face from the start only really confused me about it.

Emacs can read news, mail, and RSS feeds (M-x gnus):

Awesome! That’s interesting, though most people don’t know what RSS is and still don’t know what M-x is. But telling them some basics of what it can do is good.

You can even play tetris in Emacs (M-x tetris):

Good again. But let’s not throw games at them while they’re brand new and still don’t know what commands are. We can put stuff like that towards the end of the tutorial.

You might see now why some people consider Emacs to be not merely a text editor but
almost a complete operating system. Some users find that they can do almost all of their
work from within Emacs.

Good. Most people don’t really know what an operating system is, but it’s not that scary a word/concept to start with. Most people have at least heard of what an operating system is so it’s not going to make them uncomfortable.

These approaches, and more, are going to be addressed in my new tutorial which I posted that I’m working on. I hope that clarifies it a bit? 🙃

Summer Emacs ☀️🐃 

P.S. I should reiterate that my idea is *not* to take away the info pages above in any way, or change them, but just to add one for complete newbies. I don’t want to change Emacs in any way other than add to it with just a section for complete beginners. Nothing, and I mean nothing, is going to be changed by me in any of the tutorials or info pages. All I’m doing is creating a new section for people who don’t have a clue and could be Emacs users with a little help.

P.P.S. If you want an idea of the kind of breakdown and tone I’m trying out, check out the page I’m working on now.


[-- Attachment #2: Type: text/html, Size: 7306 bytes --]