Re: docstrings and elisp reference

[Nikolay Kudryavtsev]

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