Hi,

I recently became aware that "An Introduction to Programming in Emacs
Lisp" is non-discoverable, to the point that I doubt that any of the
target audience will be able to find it; I think this is something
that is hurting Emacs adoption rate, and there is some overlap between
this RFC and my DebConf17 documentation improvement proposal.  Looking
at the existing bugs (what users want), here is what I propose:

1. I think it's worth having a "too long" long description for
bin:emacs (and maybe emacs-nox) that notes the most significant
documentation that new users will need.  Eintr.info is one of these,
and I think that that document in particular is essential to
empowering new users, and that without this empowerment, learning
Emacs is a lot of work for a very distant dream.  Being able to
keyword or pattern search from apt, or a GUI frontend is invaluable,
and because in Debian we want users to avoid non-free whenever
possible, the manual titles (or keywords) need to be in bin:emacs.  I
would assume that it's not needed in emacs-nox, unless blind users
prefer the -nox variant and having the titles (or keywords) in
bin:emacs but not bin:emacs-nox would reduce accessibility for these
users.

2. As for #627434, I'm not sure if a package rename would be best, or
if emacs-common-non-dfsg should "Provide: emacs-doc", and maybe also
create a symlink to /usr/share/doc/emacs-doc.  It would be nice if
src:emacs documentation could be more unified, but the maintenance
burden and regression risk of this is higher, so I'm not sure if
proceeding along a "more unified documentation" avenue would be wise.

3. I fully support #893711 with one specific qualifier: I think the
single vs multiple page question should be decided by whichever is a
better source for conversion to ePubs; I suspect this will be the
multiple page variant.  On this topic, I still think that ePub is a
superior format to plain HTML, because readers are ubiquitous, and
because it provides a more book-like (yet reflowable) experience with
the option for an ever present table of contents (like PDF, and more
visibly than Info).  And of course, this format provides a more
consistent experience across many different types of devices.  I may
be biased, but it seems to me that the only advantage of HTML is that
it can be grepped/silversearched/etc; however, desktop indexers
(Tracker, Baloo, Recoll) handle ePub just fine.  But I digress...
Other than to say that many (most?) DDs outside of the Python Team
don't seem to know about the alleged consensus of Policy §12.4.  Yes
really, I've asked many over the years, but admittedly this is
anecdotal.  To be clear, whatever the case, I think that
discoverability for new users should be the focus, because everyone
else knows where to ask, or what to search for...unless we have a
morbid discoverability problem!

4. Now for more experienced users, we also have docbase.  Yeah, it has
become optional rather than recommended, but maybe it would be nice to
have?

5. Did I miss anything?  Is there any hope of getting these
documentation discoverability fixes into bullseye as a stable-update?

Comments welcome!  I am volunteering for this work; however, I cannot
commit to it before October, and I would sincerely appreciate if any
interested parties would ping me at that time.  Oh, and of course I'll
submit an MR, subject to Rob's approval :-)

Sincerely,
Nicholas

Hi,

As long a your messing about with the documentation
attached is a 1 page (or 2 if you want to keep reading)
doc on getting started with emacs.  If you feel it would
be helpful to include (somewhere), please do.

I'll license it in the public domain, or gplv3, or whatever
you think might get it into the most visible place/package.

I'd be happy to redo in RST (or docbook v5) to support
multiple formats.

Feedback on content is also welcome.

Regards,

Karl <kop@karlpinc.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

Hi Karl,

"Karl O. Pinc" <kop@karlpinc.com> writes:

Thank you for your enthusiasm and desire to make Emacs more
approachable!  For the documentation you've proposed to be relevant to
this bug, it would need to be part of upstream Emacs documentation, so
that's one option.  A notable barrier to this avenue is the Developer
Certificate of Origin, and the potential issue of attributing copyright
to the FSF, but that said, it's a good option.  At this point I'd use
whatever source format you're most comfortable with; later, if you
wanted to upstream your work, you'd contact upstream, ask where they
think it would "fit" into the existing upstream docs, convert it to the
format used by the rest of upstream Emacs documentation, and submit a
patch.

I was able to find two web pages with good "First Steps in Emacs" type
documentation, so I agree that there's a need, and that there are also
other people who are interested in solving this problem.  It might be
worth collaborating to share data on pitfalls that new users experience,
and the "many eyes" approach helps to defend against "paradox of
knowledge" type assumptions made while writing documentation.  To take
this path, host a git repository of your project, write a README with
clear objectives, of course share what you have, and reach out to forums
and people who seem like they might be interested.  If your intent is to
eventually upstream the Quick Start Guide, please include this fact in
your README, along with links to what is required.  eg: all significant
contributors would need to be willing to attribute copyright to the FSF
and comply with their DCO checks.

Ideally it would also be nice to see footnotes and/or links to existing
documentation to provide direction for further growth for a new user who
has succeeded in their first steps.  It's also a challenge to find the
balance between not enough info, and too much info, but I agree that a
simple guide is a good idea, because it provides fast positive feedback
that encourages further learning.

I also think that the "Emacs Tutorial" could use some edits, to
communicate the value of its approach.  Eg: The "why", and for example I
remember feeling that the cursor movement section was neat, but
anachronistic, and I didn't see why it was worth learning until many
years later.  I sometimes wonder if Emacs' existing documentation is a
form of gating, if it's purposefully designed as a "quest", or of the
"paradox of knowledge" principle is in effect.  It's high quality
documentation, but yes, I agree, whatever the cause may be, it could be
more approachable and discoverable.

In addition to the Debian Emacsen Team mailing list, here are links to
other forums where you may be able to find collaborators and/or people
who are willing to provide feedback:
https://www.emacswiki.org/emacs/EmacsForums

Of course, it's also completely acceptable to work on it alone!
Personally I prefer team work, because it encourages me to continue
working during times when I lack motivation ;-)

I hope this email finds you well, and encourages you!
Best,
Nicholas