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

[joakim]

"Eric S. Raymond" <address@hidden> writes:

please see nics work in this area.

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

-- 
Joakim Verona