From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: On being web-friendly and why info must die Date: Fri, 05 Dec 2014 17:43:54 +0200 Message-ID: <83r3we2jb9.fsf@gnu.org> References: <20141205123549.GA29331@thyrsus.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1417794251 11415 80.91.229.3 (5 Dec 2014 15:44:11 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 5 Dec 2014 15:44:11 +0000 (UTC) Cc: emacs-devel@gnu.org To: esr@thyrsus.com Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Dec 05 16:44:04 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Xwv36-00007b-DX for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 16:44:04 +0100 Original-Received: from localhost ([::1]:51074 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xwv36-0004F9-1x for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 10:44:04 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39123) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xwv2n-0004Ey-NO for emacs-devel@gnu.org; Fri, 05 Dec 2014 10:43:52 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Xwv2h-0005bD-7X for emacs-devel@gnu.org; Fri, 05 Dec 2014 10:43:45 -0500 Original-Received: from mtaout23.012.net.il ([80.179.55.175]:53233) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xwv2g-0005aj-VN for emacs-devel@gnu.org; Fri, 05 Dec 2014 10:43:39 -0500 Original-Received: from conversion-daemon.a-mtaout23.012.net.il by a-mtaout23.012.net.il (HyperSendmail v2007.08) id <0NG40030083TDB00@a-mtaout23.012.net.il> for emacs-devel@gnu.org; Fri, 05 Dec 2014 17:43:37 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout23.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NG4003V390OAQ60@a-mtaout23.012.net.il>; Fri, 05 Dec 2014 17:43:37 +0200 (IST) In-reply-to: <20141205123549.GA29331@thyrsus.com> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 X-Received-From: 80.179.55.175 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:178940 Archived-At: > Date: Fri, 5 Dec 2014 07:35:49 -0500 > From: "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. 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.