Re: More metaproblem

[Stephen Leake]

Drew Adams <address@hidden> writes:

>> Whenever someone on this list says "please follow the standard",
>> they should _also_ mention ./CONTRIBUTORS, or one of the more
>> detailed files in admin/notes. That will get people used to
>> refering to those files, raise awareness of them, and encourage
>> people to keep them up to date.
>
> Yes.
>
> That's the same kind of thing we do for user questions about
> Emacs Lisp coding conventions etc.: (a) answer the question,
> but also (b) refer them to the relevant doc about it in the
> manuals.
>
> Would it hurt to put the information you refer to, which is
> aimed at Emacs contributors, into the Emacs manual, as a
> separate section?  

There is such a section; (info "(emacs)Contributing). It just references
address@hidden, http://savannah.gnu.org/projects/emacs/ and
etc/CONTRIBUTE.

I'll fix the latter reference.

As you say below, I don't think we should duplicate the information in
the two files, but I would not be averse to moving the info into the
manual, and leaving ./CONTRIBUTE as a reference. That would allow the
links I just added to ./CONTRIBUTE to be more clickable, since the
texinfo is pushed to the web at
http://www.gnu.org/software/emacs/manual/emacs.html, and urls in Emacs
info also bring up a web browser.

> A priori, that makes sense to me, but then
> I don't see a logical separation between Emacs users and Emacs
> contributors anyway.

I certainly moved gradually from user to contributor.

> IMO, it does not matter whether such info is detailed, boring,
> internal stuff.  It would still be good to move it from other
> files to the official doc, and give it the proper love that
> such doc requires.

I consider ./CONTRIBUTE to _be_ "official doc". Why do you think
otherwise?

> I think that doing this might have these benefits:
>
> 1. Put more of an accent on it, for everyone.  

That comes from _advertising_, not from format.

It makes it a little more accessible. But ./CONTRIBUTE is on the web
now: http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE

I just did a Google search for "Emacs contribute". The first two links
are:

http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html

    Excellent! I need to understand exactly how/when that is updated.

http://www.gnu.org/software/emacs/CONTRIBUTE

    a currently out of date copy; again, I need to understand exactly
    how/when that is updated.


followed by other not-so-relevant links.

How much more accessible does it need to be?

>    The content
>    and form would need to be clear and complete, 

That comes from editing skill (I have yet to hear if my edits are
acceptable). 

>    and kept up to date, but that should be the case anyway.

That comes from developer attention, which is mostly influenced by
advertising.

> 2. Let users know that they can contribute, 

That is certainly implied by the Free Software nature of Emacs.

Although the climate of other developers is a big factor once people
consider contributing.

> and just what's involved (yes, in detail).

I don't see why the format affects this.

Some have suggested that the current crop of potential contributors are
more comfortable reading web stuff than file stuff; do you agree with
that? 

> 3. Encourage people to reference it, as they do now for
>    questions about key-binding conventions etc.

I don't see why
http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
would be a better/simpler/easier reference than ./CONTRIBUTE.

If you need to read ./CONTRIBUTE, you already have the source on your
disk.

Exception: the short list of "other ways to contribute" should be on a
web page somewhere.

> Just a thought.  Disclaimer: I'm not familiar with the
> info I'm conjecturing about.  

Please take a moment to read it; it's only 339 lines, about 1/3 white
space. 

-- 
-- Stephe