[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: docstrings and elisp reference

From: Nikolay Kudryavtsev
Subject: Re: docstrings and elisp reference
Date: Sat, 10 Jun 2017 14:36:12 +0300
User-agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.1.1

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]