Re: More metaproblem

[Karl Fogel <kfogel@red-bean.com>]

Stephen Leake <stephen_leake@stephe-leake.org> writes:
>> It's not just a matter of contributing documentation.  We don't even
>> *have a place to put such documentation* right now.
>
>As others have pointed out, we do have such a place, but most people are
>not aware of it. That needs to change, and I'm working on implementing
>the changes suggested so far.

Bravo to you!  Thank you.

I think a web page as the gateway is important, though:

There needs to be place where a developer *who has not yet decided to
contribute to Emacs* can land and quickly get an impression of how much
work is involved, and what the nature of that work is.

If that impression is only available from a place like etc/CONTRIBUTE,
then we're effectively asking people to have made that decision before
they've gotten the information they need to be able to make it.

It can be maintained in the Emacs tree, but it needs to be published in
a Web-standard way outside that tree (i.e., browsing to it in the
web-based git repository browser would be a poor user experience).

>Emacs was around long before "web pages". It has been slow to embrace
>web pages, because it already has a culture that works well without
>them.
>
>Perhaps that needs to change to attract new blood, but I'm not sure.
>Emacs has a _very_ different feel than "typical" development
>environments; using a unique development environment for creating Emacs
>can ensure that is maintained.

Even people who use Emacs for almost everything rarely use it as their
primary web browser.  A few do, but most don't.  As I think across all
the Emacs-first developers I know -- people like me who use Emacs as
their shell, as their mailreader, as their primary development
environment, as their primary text composition, and as their organizer
via Org Mode -- they still use a dedicated browser like Firefox for
browsing the web.

(No doubt a few people here use Emacs as their primary web browser, but
I'm pretty sure that's the exception, even among heavy Emacs users.)

So for information that people typically expect to be on the Web, such
as developer guidelines for contributing to a free software project,
we'll be better off putting that on the Web.  Because the people who
need to read it the most, the people who are the most important to us --
proficient Emacs users who are *considering* becoming contributors but
who have not decided yet -- will expect to find it on the Web anyway,
and will most likely first read it in an environment other than Emacs.

One solution would be to write those docs in (say) Markdown and
autogenerate the HTML pages, so that reading them and editing them in
Emacs is easy, but we still get HTML for the web site.

-Karl