On being web-friendly and why info must die

[Eric S. Raymond]

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.

I think the major reason this has not happened is because the Emacs
development culture is still largely stuck in a pre-Web mindset.
There are a number of historically contingent reasons for this, but
enumerating them is not really important.  What matters is recognizing
that this is a problem and fixing it.

There are two reasons it's a problem: one of capability, one of
positioning.

The positioning problem is that info/Texinfo makes us look like a
steam-powered archaic joke to younger developers.  Text-only
presentation with obtrusive links and a complex command set for a
viewer that's *not a web browser*?  In 2014?  Really?

The capability problem is that the younger developers are objectively right 
to laugh.  Because these resources are not rendered to Web, they're an
informational ghetto with an impoverished internal link structure.  The
fact that some of them, like /etc/CONTRIBUTE, are plain text with no
link structure at all certainly doesn't help.

The EmacsWiki is a valiant stab at fixing part of the problem, but its utility
is severely damaged by the fact that it can't readily link inwards to
the stuff carried in the distribution.

The solution must be partly a change in mechanism and partly a change
in policy and attitude.  The change in technology is the simple part;
info and Texinfo must die.  They must be replaced with a common format
for documentation masters that is Web-friendly, and by Web
presentation.

I have discussed this with RMS and, pending my ability to actually write
proper translation tools, we have agreed on asciidoc as a new master 
format.  This is what should replace Texinfo and the gallimaufry of
ad-hoc text files like /etc/CONTRIBUTE and the admin/notes stuff.

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?
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>