Re: More metaproblem

[Stephen Leake]

Karl Fogel <address@hidden> writes:

> 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.

The _first_ thing I do when considering a project is to download the
source code, and browse thru it. That tells me a lot about the culture,
and whether I could stand to edit the code.

The only things I get from project web pages are a sense of how many
developers there are, how involved they are, how long the project has
been around, what language and what CM system are used.

The mailing list archive and bug tracker are good sources of
information on the first few items.

Other information on a typical project web page is aimed at people who
might _use_ the project (ie a user guide/manual), as opposed to
contribute to it.

> 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.

Having just edited CONTRIBUTE, I must disagree.

The sort of details that are in CONTRIBUTE are things that I would only
worry about _after_ I had decided to work on a project, based on the
above browse thru the code.

There is a brief list "things you can work on other than code"; it's
pretty standard, but it would make sense to have that on a prominent web
page. 

CONTRIBUTE mostly talks about Changelog formats and how to use git;
minor details (but frustrating when you don't know them).

I was put off by bzr; but the information about which CM system Emacs
uses is on the main Savannah web page, so there's no need to consult
CONTRIBUTE for that.

> 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).

A direct link to CONTRIBUTE in the web-based repository browser would be
a good thing for the Savanah web page. Since CONTRIBUTE now
references the wiki, along with several other sources of information, it
might make sense that it be starting point.

Hmm. It would be nice if the web links in CONTRIBUTE were presented by
a non-Emacs browser as clickable links in that case. Currently, you
have to copy and paste to the address bar.

Of course, if you browse the web in Emacs, or just read the text file in
Emacs, they _are_ clickable!

So perhpas the first line of CONTRIBUTE should be "This file is best
read in Emacs" :).

But it's probably best to keep the wiki as the primary reference from
the Savannah web page, and have it explain about CONTRIBUTE.

I'll work on the wiki next, but it's much more of a mess than
admin/notes/*

Which is a big reason I prefer files in the repository over a wiki; the
repository is kept much cleaner, because people review it.

>>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.

True (I use Emacs as you do). But I don't see how that addresses the
question of where the information in CONTRIBUTE should reside.

> 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.  

Every free software project I've worked on has the "how to use our CM
system" info in a file in the CM repository, not on the web. (that
includes monotone, emacs, opentoken, dvc).

So apparently we have very different experiences, or we are 
talking about different information.

> 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.

People who write elisp for Emacs must be used to reading the elisp
source.

That doesn't mean they have the repository checked out; the "binary"
install includes the elisp source, but not the full source tree.

Many people who use Emacs compile it from the release tarball, to get
the latest release.

For others, it's a pretty small step to either unpack the release
tarball or checkout the git repository.

So I don't see a significant barrier here.

> 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.

I would not mind doing that (that's how it works in monotone), but I
don't see how that addresses the original problem, which was that
several people who were contributing were unaware of the documentation
on the processes.

And it definitely takes resources to support; the machinery that does
this in monotone breaks occasionally.

-- 
-- Stephe