@mikpe Same here
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
). 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
). 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
”.
A side note on the argument of being friendly to newcomers. Nothing against that (hi new guys, welcome to Erlang
). 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
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.