Documentation usability feedback

Welcome @Elias!

You can find it at the bottom pages, as you can find it here: API Reference — kernel v10.4.2 (search for “Download ePub version”). But the page you linked indeed doesn’t have one, perhaps because a configuration flag was missing when generating it.

On the topic of navigating the docs, if you do browse the documentation say Erlang/OTP 28.2 — Erlang/OTP v28.2 in your cosy dark–mode settings and decide to search for something using ‘/’ typing something and pressing Enter you are blinded by a WHITE PAGE showing the results!?

You’ll need ample time to recover from this shock, making for a loss of productivity. :wink:

1 Like

The trouble is that it is not consistent what EPUB I get! So I open the complete Erlang docs and see all of OTP 28.3. Then depending on what I click I will see different levels of docs:

  • if I click any subtitle to “System Documentation” I get an EPUB for the whole System Documentation. :+1:
  • if I got to “Core” and click on any of the applications I will get just that app :-1:
  • if I got any of the other subtitles and click on any of the applications I will get just that app :-1:

So there is no consistency! Why can’t it be that if I click on a title I get all of that section and if I click on a sub-title I get just that sub-title section?

Really go KICASS! (Keep It Consistent And Simple Stupid)

1 Like

I’d probably use Ctrl-F find anyway to locate the function

Not me. In these cases (looking up the details for a known function) I’m just using the mouse and scroll wheel to locate it. Having to search would mean shifting to the keyboard, which would be a lot more inconvenient.

4 Likes

@mikpe Same here :+1: If I had wanted to move my hands that much, I would rather have become a DJ or shell player…


With the old documentation, my “workflow” when I wanted to get documentation on something was like this: I usually knew the module or the likely module. I would google it (I never managed to find my way through the application groups and stuff :sweat_smile:). Then scroll through the list of functions. When I knew exactly which one I wanted, I would also know how often to tap the mouse wheel; if I didn’t know exactly, I would let my eye catch on likely candidates as they were scrolling by. (Other than what others posted, modules with so many functions that scrolling becomes tedious are rare AFAICT). Only as a last resort would I resort to ^F to find some word that was likely to appear in the context that I was looking for when no function by its name suggested that it was the one I wanted.


With the new documentation as it is now, I usually still start with googling the module (I still can’t figure out the application groups, googling is still faster :sweat_smile: :sweat_smile: :sweat_smile:). But now I’m faced with the groups, have to read which groups there are to begin with, then think in which group the function I want would fit best. Worst case(s), it fits none, or several, or the function is actually not in the group where I would look for it at all (erlang:abs/1 is a good example… it’s in the “Erlang Terms” group, which is not really where I would look for it; in fact, none of the groups are really fitting for it…). So I open group after group to scan for it, always starting again scanning from “A” to “Z”, only not to find it there and open the next group, repeat ad nauseam. After having done that 2, 3, 4 times, I reach for ^F, more often and for other reasons than before with the old documentation, have to switch over to the keyboard, push several+ keys… (vs the scroll wheel once or twice, which is exactly where my hand already was). But then, you get every occurrence of the search string in the document, not just the function (again, erlang:abs/1: if you ^F for “abs”, you get 26 hits, including “absoluteURI”, “abs_path”, “absence”, …, most of which have absolutely nothing to do with the function that will get you the absolute value of a number.


See, I’m not against having groups. They may be good for newcomers, or they may not, that’s not the point. What I am saying is that the absence of an alphabetical index is actually hindering advanced users. That is, why can’t we have an alphabetical index alongside the groups? I mean, every reference manual (yes, on paper) I have ever seen had a table of contents (which is something like the groups) and an alphabetical index (even the Bible has that in any even remotely recent edition). Having only the groups is like having only the ToC, and when looking for something you are wondering “Weeell then… what chapter would be the one where I could find that? This one maybe? (browse) (read) No, that wasn’t it. Maybe this one? (browse) (read) No… Guess I’ll have to skim the entire book then :flexed_biceps:”.


A side note on the argument of being friendly to newcomers. Nothing against that (hi new guys, welcome to Erlang :waving_hand:). But the goal should be to turn newcomers into advanced users, that is, the number of advanced users is going to grow even while the number of newcomers remains the same. If the documentation only serves you well as long as you are a newcomer but it’s value diminishes as you become advanced… well, think about it :woman_shrugging: I guess I’d feel kinda tricked. Only, I had already sold body and soul to Erlang before the new documentation happened and learned ways to cope with it.

3 Likes

Adding to that: When I scan through an alphabetical listing and don’t find the function I’m looking for there, I can be sure that it isn’t there and that I am probably looking at the wrong module (like, io vs io_lib, file vs filelib, …).

With the groups (only the groups, that is), if I don’t see it in one group, it may still be in another. So only after having scanned through them all (or ^F-ed, which gives you all occurrences, which you will have to examine forthwith) can I be sure that it is really not there.

tl;dr: let’s have an additional alphabetic index, pretty please :sweat_smile:

3 Likes

Hello everyone!

I’m the person responsible for many of the groups in the docs and just returned from parental leave so I’ve missed this discussion until now, though I’ve heard others bring up these issues before.

I just thought I’d try to answer some of the questions/complaints about the new docs, focusing on the group discussion.

tldr: There is a new PR that tries to make things better: Polish documentation groups by garazdawi · Pull Request #10755 · erlang/otp · GitHub

Grouping

I’ve always had issues remembering which modules are in kernel vs stdlib, so when (the IMO excellent) algolia search was introduced I started using it for all my navigation. The groupings of modules and function is a similar problem, but I’ve not experienced it myself as using search makes it a non-issue. That being said the docs should of course be as easy to navigate as is possible for everyone.

The groups in the docs are an attempt to try to help the user to know which functions/modules are useful in a certain area. For example in zip there is a group for functions that are only there in order to make it possible to quickly change from erl_tar to zip. In stdlib there is a module group for things related to process management to make it obvious that modules like sys and proc_lib deal with processes.

When grouping things together like this it should be immediately obvious to everyone which group a certain function/module belongs to. This is not the case right now and guaranteeing that it is obvious to everyone is impossible.

Grouping of functions

In the old docs there was one way to do groupings, you could group function in the actual documentation page. As an example we have Rand’s Plugin Framework API which is a grouping of certain functions within the rand module. The grouping was not reflected in the function listing so I assume (possibly incorrectly) very few people knew it even existed.

When migrating from erl_docgen to ExDoc I chose to keep those groupings as I assumed that the author of the docs had a good reason to group those functions. I also added groupings to erlang in order to try to make it easier to navigate within the roughly 300 functions in the module.

Grouping of modules

Groups of modules in used in 4 applications; stdlib, kernel, compiler and inets. The number of modules within compiler and inets is minimal so I don’t see those as a big issue. For stdlib and kernel I see why navigating via the module listing is not idea, though there is the api-reference list which should serve as an alternative, though not as convenient as using the sidebar.

When creating the module groups I felt that it looking nicer in the docs when each module belonged to a group so I was a bit overzealous with their usage.

Steps forward

I’ve opened a PR that removes many of the groups. Please have a look and see if you think it is an improvement. I’ve kept the module groups for now as I do think they are useful and the api-reference list exists in order to get a group-free listing.

The ssl, ssh and crypto applications still use a lot of function/type groups. I’ve not touched them as I don’t know enough about them to make good decisions about which, if any, groups there should be.

6 Likes

There is a fundamental lesson from information retrieval: ALL classification systems are inadequate. This includes things like Dewey and Library of Congress systems for libraries, and less obviously it includes the Linnean system in biology. It also includes groups of functions and modules. There is no one right way or even best way to do that. People havebeen expressing dissatisfaction precisely because the groups are not serving their information needs well.

Hands up everyone who has used a knife as a screwdriver? Anyone else (ab)used a pair of pliers as a hammer? Cut a package open using a key?

The main problem with groups is that they are not generally predictable. Let’s take Smalltalk as an example. Suppose I am looking for a method to apply a function to each element of a container and answer the element with the largest value. Will it be in the “apply a function to elemts” group or in the “summarising” group? The only reasonable answer is “yes”, but Smalltalk won’t let me put a method in more than one category (group).
I’ve just been looking at some Clojure documenation organised by groups, and it’s a huge pain in the situpon. Time after time I’ve thought something didn’t exist and started to program around the gap but it turned out to exists but not fit in the groups.

The answer is to let people CHOOSE between a complete synoptic view and one or more classifications. Search, alas, only works when you know what to search for. Improving the groups in one classification is very nearly futile.

3 Likes

I don’t think removing the groups entirely is the way to go. Looks like there is some value in that for newcomers, as @michalmuskala and others pointed out (though as @nzok also pointed out, there probably is no one good way to group something). Anyway, what people seem to object to is that with groups, there is only the groups, that is, a simple ungrouped listing is gone.

3 Likes