From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!.POSTED!not-for-mail
From: Nikolay Kudryavtsev <nikolay.kudryavtsev@gmail.com>
Newsgroups: gmane.emacs.devel
Subject: Re: docstrings and elisp reference
Date: Sat, 10 Jun 2017 14:36:12 +0300
Message-ID: <1f0a4527-e669-a618-8864-baf9ec4c27e0@gmail.com>
References: <E9B4FFDA-34F4-45DA-A37E-C431A1E55310@gmail.com>
	<alpine.DEB.2.20.1706060901460.2311@calancha-pc>
	<0BB64F35-233A-471F-B99F-51F96C4E6CCB@gmail.com>
	<8360g99n07.fsf@gnu.org> <86lgp4q2xa.fsf@stephe-leake.org>
	<7acc7d4f-23cc-4b6a-b062-ef92805e465b@default>
	<878tl3rz38.fsf@x230.lts>
	<E1dJBFn-0001Vt-V3@fencepost.gnu.org> <877f0ln3dx.fsf@x230.lts>
	<83poed7i4t.fsf@gnu.org>
	<CAP_d_8VOctpy_pjk816D2pA3XWAtsEvHMNo+GYm8NeMuryDz0g@mail.gmail.com>
	<83o9tx7b7d.fsf@gnu.org> <83mv9h73o1.fsf@gnu.org>
	<CAP_d_8V7467HdekocZE99mWb8d74KHbcozF_3TRA=r2QCwjV1A@mail.gmail.com>
	<83lgp16zpw.fsf@gnu.org> <87h8zpge1y.fsf@x230.lts>
	<54A01FC0-6692-411D-91CB-764402C7BF14@gmail.com>
NNTP-Posting-Host: blaine.gmane.org
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
X-Trace: blaine.gmane.org 1497094627 17186 195.159.176.226 (10 Jun 2017 11:37:07 GMT)
X-Complaints-To: usenet@blaine.gmane.org
NNTP-Posting-Date: Sat, 10 Jun 2017 11:37:07 +0000 (UTC)
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101
	Thunderbird/52.1.1
To: Jean-Christophe Helary <jean.christophe.helary@gmail.com>,
	emacs-devel <emacs-devel@gnu.org>
Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jun 10 13:37:03 2017
Return-path: <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>
Envelope-to: ged-emacs-devel@m.gmane.org
Original-Received: from lists.gnu.org ([208.118.235.17])
	by blaine.gmane.org with esmtp (Exim 4.84_2)
	(envelope-from <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>)
	id 1dJehQ-00044J-HC
	for ged-emacs-devel@m.gmane.org; Sat, 10 Jun 2017 13:37:00 +0200
Original-Received: from localhost ([::1]:58015 helo=lists.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>)
	id 1dJehV-0001Gy-RQ
	for ged-emacs-devel@m.gmane.org; Sat, 10 Jun 2017 07:37:05 -0400
Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:59916)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <nikolay.kudryavtsev@gmail.com>) id 1dJego-0001Gr-Ek
	for emacs-devel@gnu.org; Sat, 10 Jun 2017 07:36:23 -0400
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <nikolay.kudryavtsev@gmail.com>) id 1dJegl-0008G9-Ci
	for emacs-devel@gnu.org; Sat, 10 Jun 2017 07:36:22 -0400
Original-Received: from mail-lf0-x230.google.com ([2a00:1450:4010:c07::230]:34804)
	by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16)
	(Exim 4.71) (envelope-from <nikolay.kudryavtsev@gmail.com>)
	id 1dJegl-0008Fp-5Q
	for emacs-devel@gnu.org; Sat, 10 Jun 2017 07:36:19 -0400
Original-Received: by mail-lf0-x230.google.com with SMTP id v20so37585153lfa.1
	for <emacs-devel@gnu.org>; Sat, 10 Jun 2017 04:36:17 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025;
	h=from:subject:to:references:message-id:date:user-agent:mime-version
	:in-reply-to:content-transfer-encoding:content-language;
	bh=3eqU73EBQPfjafOWW0uFz7X8ct9kZmSytV3P27bUoBk=;
	b=So7sgXy+xp4WTs272a5TEES+kW5lJcWYTuCJ+FSy1esHqt5zb+Udw1MFGp0MX8p+aM
	tGaDCHStXY67IkdybcnEfu8Fb6eRZQ4/4inhfW9v2gnV4Hx7Td64E3ha2hjgVjWsyz75
	5VXrtGmQiZCfxTcQBteFlD89iTTlabyItWaVbb20VSaBS3L2ZGatRC0FbRjXWPrhNakJ
	L6mcySLC3jKAXtxWgMZHv4X0cG76SgamYuJNga0T8egPHx0Rxv1HmSgLXqDoPESy9nyN
	i69YPZuIvwpnfrF9GIN1uNP1ZCtdVhdWO4jC30uxT1Ll4malTsv6ECmSbCoXjKtsbRC5
	Zneg==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
	d=1e100.net; s=20161025;
	h=x-gm-message-state:from:subject:to:references:message-id:date
	:user-agent:mime-version:in-reply-to:content-transfer-encoding
	:content-language;
	bh=3eqU73EBQPfjafOWW0uFz7X8ct9kZmSytV3P27bUoBk=;
	b=knbFYtS4cFxEpTvg2PSqkH8l7aXMXO10E72ucZ00y39Dxy7S8Ajizcn5kVHzBRax7z
	2BqLP1Tl4Wt+xlOnNdk+Dv3FZp3NaeO99Sl/5xelJDZWoonBHLD5BGR+k7BGchTGQ8w6
	mdiB5z6SVtaDRj0rN7XSROtvwxsMzD+99Oba60Vf7JsaB9GbywoYZxi4XRdktplk0rDN
	AkN8Al+PNE2vCpY2lkq7q9nOzD6x4XytfQt5xNe2IcyItd2b+UR/m8uu7zhkOSulXmD6
	byK63HoXg5/UKXV8rOA+IvEKTZ0tJEHo+Vdwx3STpcYsHrCurvS6aVFx6AdeVsNKLSu8
	Qfjw==
X-Gm-Message-State: AODbwcCTigdg13GwWAe71sZbXnEs/AFcVsI6EJxMYUfCQkKIJaJxzwxm
	6MJxU+hfedz3rv1Y
X-Received: by 10.46.6.2 with SMTP id 2mr933567ljg.136.1497094575763;
	Sat, 10 Jun 2017 04:36:15 -0700 (PDT)
Original-Received: from [192.168.199.6] (broadband-95-84-209-126.moscow.rt.ru.
	[95.84.209.126])
	by smtp.gmail.com with ESMTPSA id r38sm1005294lfi.4.2017.06.10.04.36.14
	(version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);
	Sat, 10 Jun 2017 04:36:14 -0700 (PDT)
X-Google-Original-From: Nikolay Kudryavtsev <Nikolay.Kudryavtsev@gmail.com>
In-Reply-To: <54A01FC0-6692-411D-91CB-764402C7BF14@gmail.com>
Content-Language: en-US
X-detected-operating-system: by eggs.gnu.org: Genre and OS details not
	recognized.
X-Received-From: 2a00:1450:4010:c07::230
X-BeenThere: emacs-devel@gnu.org
X-Mailman-Version: 2.1.21
Precedence: list
List-Id: "Emacs development discussions." <emacs-devel.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-devel>,
	<mailto:emacs-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/emacs-devel/>
List-Post: <mailto:emacs-devel@gnu.org>
List-Help: <mailto:emacs-devel-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-devel>,
	<mailto:emacs-devel-request@gnu.org?subject=subscribe>
Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org
Original-Sender: "Emacs-devel" <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>
Xref: news.gmane.org gmane.emacs.devel:215554
Archived-At: <http://permalink.gmane.org/gmane.emacs.devel/215554>

What's important to understand here is that docstring documentation is 
of very limited use. This applies to both Emacs docstrings and 
everything created by javadoc and its cousins.

Let's say I want to do something with an API that I have no prior 
knowledge of and I have only the docstring documentation. I start by 
searching docstrings for something that looks vaguely useful for solving 
the problem at hand. Would the first thing(be it a class, or a function) 
I found be the optimal solution? Maybe there's actually a more 
specialized version of this function that better suits my case. Or maybe 
it's the opposite - I stumbled into a specialized function, where the 
broader one is more suited for me. There's no way to know until you read 
everything that looks even slightly important.

Because of this, the documentation needs some glue, that puts separate 
elements into a proper context. Docstrings are incapable of solving this 
problem yet. You can't just have docstrings that go "if you find this 
function useful, maybe you actually need this-other-function or maybe 
this-totally-other-function".

The key word here is _discoverability_. Because of this, you can't just 
dispose for example of Elisp manual, since it's exactly that rug that 
ties the room together.

I'm not saying that it's impossible to build a better documentation 
system than we currently have in info. It's just a massive investment 
that would at best be a very slight improvement.

As a practical example I installed Zeal and downloaded MySQL manual for 
it. It has different indexes, but there is no table of contents(1). 
Let's say I want to calculate a logarithm. I go by function index and 
find one of the log functions. Luckily that's the full MySQL Reference 
Manual and not some javadoc abomination and it provides all log 
functions within the same context, and that within a broader context of 
math functions. Also I can't search the whole manual at once, only 
indexes or a single chapter(2). And it's worth noting that the search is 
just a dumb text search(just as in info) and not some natural language 
processing one as proposed by Etienne Prud’homme in this thread. So, due 
to 1 and 2 Zeal is not superior to info in usability, while 
discoverability is a feature of the material and not presentation.

-- 
Best Regards,
Nikolay Kudryavtsev