RE: (emacs) Intro [was: Making Emacs popular again with a video]

[Stefan Kangas]

Hi,

My day-job involves copy-editing among other things.  I like this
revision overall, but hope you find the below observations useful.

First, it doesn't push the point that this is an editor for "power
users".  In my opinion, we should emphasize that point, as others have
suggested.

excalamus--- via "Emacs development discussions." <emacs-devel@gnu.org>
writes:

> Updated the proposed intro based on everyone's excellent feedback!
>
>> (nil)Top
>>
>> Welcome to the Exciting World of GNU Emacs!
>> *******************************************
>>
>> GNU Emacs is born of two ideas, the GNU project and Emacs editors.  The

"Emacs editors" here is confusing.  I'm not sure how to reformulate it,
but see the below point.

>> goal of the GNU project is to provide a complete, free software system.
>> This means GNU Emacs respects you. It can adapt to how you work, not the
>> other way around![1] An "Emacs" is a command oriented text editor

Better: "Emacs is a command oriented text editor".  I understand what
you're going for (there are other Emacs editors) but frankly it's not
really a key point in an introduction and it is not easy understand this
subtle point for readers.

>> designed for introspection and extensibility.  These qualities enable
>> far more than basic word processing, as this manual describes.

Scratch "as this manual describes", it is superfluous.

>> "Introspection" means GNU Emacs has self-knowledge.  Every aspect of the

I'm not sure about replacing "self-documenting" with "introspection",
but whatever word we use I think it reads better if it starts
"Introspection means that every aspect of the system...".

>> system is documented and accessible.  Each level of inquiry has
>> tutorials, guides, and references.  It can answer questions like, "What
>> commands might help me?", "What does this do?", and, "How does this
>> work?"  The documentation extends from general concepts to the source
>> code itself!  GNU Emacs has everything conveniently in-house, at your

I would avoid using an exclamation mark here.

I would also scratch the word "in-house".  Perhaps add something that
you don't need to fire up a web browser to read documentation, but can
do it directly in Emacs itself.

>> fingertips.  See Help.
>>
>> "Extensibility" means that you can alter GNU Emacs itself.  You can
>> customize the environment, from keyboard shortcuts to color themes, and

"Color themes" is mostly an assumed feature in text editors and not
terribly exciting.  Could we find a better example?

>> most everything in-between.  See Customization.  Moreover, you can
>> create and apply new commands in real-time. These can be packaged and
>> shared with the diverse Emacs community.  Most of GNU Emacs is written
>> in Lisp.  See Emacs Lisp Intro(eintr) if you want to learn how to extend
>> GNU Emacs.
>>
>> Authors and researchers, as well as programmers, use GNU Emacs.  It has

Better: "Authors, researchers and programmers all use GNU Emacs."

>> seen active development for more than 40 years and includes innumerable
>> features; it is a heritage as much as a tool.  We love GNU Emacs because
>> we find its editing environment a rewarding experience like no other.
>> We hope you'll feel that way, too.

This paragraph is excellent.  Possibly you could try something like:

"We love GNU Emacs because we find its editing environment a rewarding
experience like no other.  It can adapt to your needs and grows with
you.  We hope you'll love using it, too."

(Just a rough draft, but something along those lines maybe.)

> First, I think it oversells the accessibility of the documentation.
> The Emacs documentation is extensive and well written.  However, I
> find it quite difficult to navigate to a concept if that thing isn't a
> function or variable.  I have been a beginner and asked myself, "What
> is a cons cell?".  I found then, as I often still do, that leaving
> Emacs (to use a web browser) yields results fast enough to not use
> Emacs itself.  Ironically, I most often wind up at the gnu.org html
> documentation.

The problem is not necessarily with your text.  It could just be that we
should should identify the problematic areas and improve our
documentation, the tutorial, etc.

> Second, the menu description is "Intro::An introduction to Emacs
> concepts" which is no longer true in this version.

I propose to rename it to "An introduction to GNU Emacs".

> However, this implies structural, if not intention, changes to the
> overall manual.

What do you have in mind more exactly?

Best regards,
Stefan Kangas