Re: Intermediate tutorial shipped with Emacs

[Eli Zaretskii <eliz@gnu.org>]

> From: Spencer Baugh <sbaugh@catern.com>
> Date: Fri, 18 Sep 2015 22:19:41 -0400
> 
> I think it would be good if Emacs shipped with an intermediate tutorial,
> covering topics beyond the basic tutorial.

It would, indeed.  The problem is, as always, what does "intermediate
tutorial" means for Emacs.

> Topics-wise, I envision it would briefly cover things like:
> - keyboard macros
> - TRAMP
> - the various ways to get help inside Emacs
> - narrowing
> - dired
> - calc
> - et cetera

Past discussions more or less concluded that there should be a series
of intermediate-level tutorials, each one covering topics in some
distinct area.  So the topics you present above, that are unrelated to
each other and probably reflect your personal interests (or even some
random selection) are probably not the way to go.  Tramp should
probably be in a tutorial dedicated to remote editing and URL-related
features; narrowing should be in a tutorial that also explains
folding, outline mode, hide-ifdef, and other similar features.  Calc
is a topic by itself (doesn't it include its own tutorial in its
manual?), perhaps together with Calculator.  Etc. etc. -- I would
suggest first to come up with a list of the areas, or at least produce
a couple of tutorials along these lines.

> The hope would be to give users a taste of some of the more advanced
> features of Emacs. Then, if they are faced with a situation that one of
> those features that they read about in the intermediate tutorial would
> be useful for, they'll search the help system for more information
> rather than be frustrated.

That's a challenge in itself: how do you give "a taste" of a feature
without describing it in full, or close to that.  The manual doesn't
describe all of the facets of each feature it covers, only the
important stuff, leaving the rest to be discovered by the user by
using the help system and the source.  You need some clear rules about
where to stop the "give a taste" description to avoid being another
version of the corresponding manual sections.

> As an example, consider narrowing. If a user didn't already know
> narrowing existed, they probably wouldn't even bother searching for the
> feature; it isn't obvious how useful until you know about it. A user
> without knowledge of narrowing would use other hacks.

A very good example.  Narrowing is described in the manual in a
58-line section.  How would you go about giving the user a "taste of"
narrowing, without essentially telling the same story in slightly
different words?  It's not trivial (but not impossible, either).

> As I said earlier, I have written such a document in org, because I
> needed reference material to provide my students when I do Emacs
> workshops. (It's still mostly a draft, and it's somewhat specific to the
> workshops, so if you want to see it send me mail.) 
> 
> So, I wanted to see if emacs-devel thought this was a good idea, or a
> bad idea, or if anyone had any suggestions. I would be happy to adapt
> the document I've already written if that makes sense.

More documentation is always a good idea, IMO.

Thanks.