RE: More metaproblem

[Drew Adams <drew.adams@oracle.com>]

> > 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
> emacs-devel@gnu.org, http://savannah.gnu.org/projects/emacs/ and
> etc/CONTRIBUTE.

Yes, I know.  That is not at all what I meant (and said), which was:

 "put the information you refer to, which is aimed at Emacs
  contributors, into the Emacs manual"

It's not about providing a reference to some local file or a
mailing list.  It's about *moving* the complete information to
the manual (the Emacs manual or a new, dedicated manual).

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

If you agree that we should not duplicate the information, then
why would you leave ./CONTRIBUTE?  That's duplication, no?

The point is to let the manual be the single source of truth.
It is a mistake (asking for trouble), IMO, to have two or more
such sources.

But I'm probably missing something that you are trying to say here.

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

It is official.  But it is not in Info form, and it deserves
to be (users deserve it to be).  That's what I meant.  Perhaps
I should have said "move it from other files to where
the rest of the official is presented to users: in Info."

(And please don't bother to nitpick about there being still
other official doc that is also not in Info form.  That can
be ignored for now, or it can in turn be considered as a
candidate for moving to Info.)

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

On the web is not in Info.  (That's in fact part of the other,
parallel discussion initiated by ESR.  *Web doc does not
sufficient Emacs doc make.*)

> I just did a Google search for "Emacs contribute"...
> How much more accessible does it need to be?

My (personal) answer is that it should be in Info, not just
on the web somewhere, and not just in a file in the Emacs
distribution somewhere, and not just as a pointer to a mailing
list somewhere.

Imagine if all of the important Emacs documentation had only
the form/accessibility you are referring to.  Would you be
content to replace the Emacs manual (Info) with a link to a
web page or a local plain-text file?  I wouldn't want that.

What's good for the Emacs-manual gander is good for the
CONTRIBUTE goose.  Make that information into a manual (Info)
or part of the Emacs manual. 

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

By that I meant also that ALL of the information about
contributing should be moved to Info.  A lot of work goes
into making sure that the information in the manuals is clear
and complete.  I can't speak to whether this is also true for
other, non-Info kinds of "official" Emacs doc.  If it is, so
much the better - just move it to Info.

> > 2. Let users know that they can contribute,
> 
> That is certainly implied by the Free Software nature of Emacs.

I think you are missing the point of my suggestion.  Putting this
information in the Emacs manual would make it much more visible
to "ordinary" users (and much more navigable).  (IMHO)

Both of my points #1 and #2 are introduced by this phrase:

  "I think that doing this might have these benefits:"

where "doing this" refers to moving such information completely
to the Emacs manual (to Info form, at least, with mirroring on
the web).

> > and just what's involved (yes, in detail).
> 
> I don't see why the format affects this.

Again, the point was to move the complete, detailed information
to the manual (Info format), NOT to simply have a reference from
the manual, as now.  The difference is whether the details are
in Info format or not, so yes, the format "affects this" - it's
all about the format (and location).

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

Probably.  But it doesn't matter whether I agree, or care.
My point is that this information belongs with the rest of the
Emacs information for users: in the manual.

It is of course important that the manuals be mirrored on the
web.  And as I (and others) made clear in the sister thread,
web access to the information is necessary but not sufficient.
Manuals on the web do not provide the features that manuals
provide *in Emacs*, from Info.  Not even close.

> > 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/Contributin
> g.html would be a better/simpler/easier reference than ./CONTRIBUTE.

No one said it would be.  I think you have not understood my
suggestion well enough.

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

Having the information on your disk is not enough.  Having it on
the web is not enough.  It should be available from Emacs, in
Info form.  It should be integrated with the other user doc.

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

I'm talking also about details that explain conventions and
methods used for developing/maintaining Emacs.

(And (why not?) detailed information about Emacs internals -
such as the doc that exists for XEmacs.  But this is not
necessarily part of what I proposed in the immediate.)

It doesn't matter what I understand or think about the particular
detailed information.  Information about how to contribute and
develop Emacs should be available to users in Info form, IMO.
That's all.

I have no informed opinion about whether all of it belongs in
the Emacs manual or it should have its own, dedicated manual.
But *Info it should be* - and mirrored on the web in the same
way as the Emacs and Elisp manuals.