Re: On being web-friendly and why info must die

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 07:35:49 -0500
> From: "Eric S. Raymond" <address@hidden>
> 
> Several recent posts in the metaproblem threads have had the common
> theme that Emacs's web resources are weak, scattered, and unfocused.
> In particular, guidance for new developers that should be public,
> prominent and webbed is buried in obscure text files deep in the Emacs 
> source distribution.

David already said everything that crossed my mind while reading
this, and I can only agree with what he wrote.  What's below are a
couple of additional comments.

> I think the major reason this has not happened is because the Emacs
> development culture is still largely stuck in a pre-Web mindset.

I disagree.  The main reason is that none of the active developers
seems to have this aspect high on his agenda.  IOW, it's the oldest
reason in Free Software: no one has stepped forward to do that.

> The policy part of the job will in some ways be more difficult because
> the requirements are harder to define.  We need to change the way we
> think about Emacs's documentation; we need to concieve and organize it
> as a single, coherent, richly linked hypertext that renders to HTML as
> its major target.  This may mean giving up on some features supporting
> rendering to print manuals; I'm not sure yet. If so, it's time to bite
> that bullet.
> 
> I'm willing to take on the tools end, but I can't do it all.  Someone
> needs to take ownership of the policy/organization end of the documentation 
> problem. Will any of the people righly complaining about this step up?

I think you are putting the wagon before the horse here.  Selection of
the tools and the language used to write documentation should be up to
the people who actually are writing most of the docs.  Those people
(full disclosure: I'm one of them) are acquainted to, and proficient
in Texinfo as the source language.  They currently know close to
nothing about AsciiDoc.  In addition, the manpower we have for working
on the documentation is already too thin, and it already started
showing in the quality of the Emacs manuals.

Moreover, the vast majority of contributions to Emacs aren't
accompanied by the corresponding documentation changes, they are left
for "the Powers That Be" (which, btw, is one major reason for slow
release process, because the missing docs need to be added/adapted
during the pretest).

Until more people start contributing to the docs, it makes very little
sense to me to change the tools, and by that cut the branch on which
we sit, documentation-wise.  That is, unless you will take it upon
yourself to be our documentation maintainer for the observable future.