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