It seems most people like the new documentation style. I do not. I actually use the documentation on a daily basis, so I am less impressed with look-and-feel and most sensitive to any degradation in actual usability.
Today I discovered that the navigation menu no longer includes applications! How is this an improvement?
At the top of the top page you can select the version from a drop down and quickly see what has changed between versions. Prior to 27 the navigation menu was organized in an Application Groups section, then that header was removed but the grouping remained. Now we have to navigate to Module Index, locate a module of the application and select the link in the third column (which is unnecessarily truncated).
This is plain obfuscation. Why would we be hiding the concept of applications? My suggestion would be an Applications section, if you want to simplify the top level navigation menu.
One of my complaints about the new style, beginning in 27, is how the modules within an application are organized. This used to be a flat list, ordered alphabetically, but is now grouped by concept(?). This impedes me because to find a module I now have to guess what group it may be in. For example to find lists in stdlib I need to know it’s a datatype and not a data structure.
Similarly in erts the functions of the erlang module are grouped by other concepts, causing me to stop and think about where to find it.
Now I realize that the root problem here is that while I actually read the documentation, few people do anymore. I do not however accept that that truism reflects on the importance of the documentation.
Not only do I fully agree with Vance regarding the structure of the documentation, but the new layout has certainly not improved as far as I’m concerned. For me as a visually impaired person, the documentation is a lot less useful. The documentation may now look more similar to the average layout of other software, but as far as I’m concerned, it hasn’t improved.
I miss getting PDFs for the documentation. In the old version there was a link which returned the PDF. If one still exists today then it has been hidden.
I also find the module concept grouping very irritating. As @vances pointed out you need to know what “group” it is a member of. Same with the functions in a module listing.
Agreed, that’s been bugging me ever since they introduced the new docs. Taking erlang — erts v16.1.2 as an example, the functions are inside groups, making it really awkward to find the function I’m looking for. I’d much prefer a simple, flat, alpha-numerically sorted list of all functions in that module.
I think the organisation of functions within a module in a flat collection or crafted into sections has different tradeoffs. If you’re a new user not familiar with the module or API, you don’t know the name of the function – groups are very helpful in presenting the different things the module can deal with and allows you to narrow down the search.
If you’re an experienced user that knows the function, but just forgot the argument order or some specific details about options, then I fully agree a flat list of functions can be more useful. However, even in that case, since most modules in stdlib have just so many functions, I’d probably use Ctrl-F find anyway to locate the function, rather than scrolling through the hundreds of functions of the erlang module. At least for me, that’s how I’ve been using the old documentation too, so not much is changed here.
In my opinion the new format is significantly friendlier to newcomers, while not hindering usability for experts too much in practice.
The great thing about electronic documentation is NOT having to make tradeoffs. I mean, this is what HTML plus the DOM plus Javscript is supposed to give you: you can change the structure, hiding abd revealing indices, even rearranging all the chunks in a page, at the flick of a button. You can automatically add “threads” so that you can read in alphabetical order or topic order or whatever.
“Yay Newcomers! Advanced users, ^F you…” (j/k, couldn’t resist the pun )
Seriously though, I think documentation should be focused on advanced users (ie, people who need it to do their job), while providing ways for newcomers to find their way around. The grouping IMO only favors newcomers and makes it harder for advanced users to find something they exactly know that they want.
I don’t mind the ordering and grouping of functions in the actual document. But I would at least wish for an alphabetical index of functions in the sidebar, alongside the grouping. I don’t see why this can’t be done.
Having to resort to CTRL+F for finding things seems to me definitely a step down, an ugly workaround necessary only because the documentation doesn’t provide a good way for that.
My point is that for a module with 100+ functions (and a lot of stdlib falls into that category), you’d use CTRL+F anyway, rather than scrolling the huge list of functions.
But I agree that an alphabetical index on the sidebar alongside the thematic indexes might be a solution.
I think there are more tradeoffs here. One problem with the alphabetical listing is that it will often show legacy/deprecated functions before the new preferred ones. Maybe the sidebar could be rendered with expanded groups?! On the other hand for advanced user why not use LSP so that you get help with the argument order in your IDE, or use the erlang shell just saying quicker than browsing html.
I repeat that there should BE any tradeoffs. Using HTml + CSS + Javascript the same single downloaded page can be resteuctured to the user’s preferwnce at the touch of a button. Let’s face it, that’s the reason SGML and X/Ht/Ml exist in rhe firzt place, to radically separate content from presentation. A reader might well NEED legacy interfaces presentex first because they need to understand existing code that uses them. Preaenting legacy i terfaces isn’t jyst notwrong, it’s sometimes necessary. Imagine, it you will,function descriptions tagged with when they were added, when deprecated, and ehen removex, witha version box so you can say “show me modules and or functions that were available in Release x.y” WITHOUT having to reload the page, just re-render it. Ths kind of adaptability to the user’s needs is the only good reason to offer HTML instead of PDF and/or man pages. Let’s have no more talk of tradeoffs.
LSP is good, but it’s not always usable. erlang_ls is archived and do not support Erlang/OTP28. And ELP only provides executable for x86_64 and aarch64. I have a RISC-V laptop (Musebook,rv64gc), no ELP on that laptop.
I tried to compile it from source, but the rust compiler of the host OS (based on Ubuntu24.04) is too old for ELP. Maybe I can build a newer rust toolchain first, but I choose to code without LSP on that machine.
I feel there are different concerns mixed here. If your goal is to find somethingyou exactly know, then using the autocompletion/search will surely be the most productive way to go about it?
You can press `/` (or `?` or click it) to activate the search
Type the module name
Press down and enter
Any other way to find a module or a function will be slower, be it in the old documentation or the new one. For example, imagine you want to find `flatmap` in the old docs. You had to scroll alphabetically until you find `lists` in the sidebar, click it, and then scroll through half of the functions and click it, which is a worse experience for those who know exactly what they are looking for compared to simply typing `flatmap` in the new docs bar.
Then there is a separate question of “I don’t know what I am looking for”, which applies to both newcomers and experienced developers. The goal of grouping is to help everyone explore the data, but groups may not work if the grouping logic is inconsistent or unintuitive or if there are too many groups.
There are also cases where the groups are, in my opinion, well done, such as the grouping of applications in the home page. So it probably makes more sense to point the specific cases where group names are not being helpful, such as `erts` mentioned by @mikpe, and work from there. Plus, if the primary goal is to avoid listing deprecated functions first, there could be a group only for the deprecated ones.
I miss getting PDFs for the documentation. In the old version there was a link which returned the PDF. If one still exists today then it has been hidden.
There is a link to download EPUBs at the bottom of every page but it is unclear if they fullfil your need for PDFs.
I know about the EPUBs but they are not as good as getting a PDF for the WHOLE application, group, OTP documentation or Erlang description in one big block. They are just the small chunks and I still need to put them together.
By WHOLE application group you mean all of the apps in a single EPUB? So one EPUB with all of stdlib, kernel, wx, etc? Because we currently include the whole individual application, with all modules and guides in it, but I wanted to be double clear on what you mean by application group.
Aye, that partially tracks with how I use it. I generally know the module and use search to find it, but then explore it by navigating.
I have also been debating adding an option to ExDoc that allows documentation readers to control if they want grouped or alphabetical but I am skeptical about doing so because, if groups are not clear for experienced developers, I am afraid they won’t be clear for newcomers either.
Groups are ordered alphabetically but they don’t have to. This means not commonly used functionality, such as `erl_tar`, ends up way higher than `lists` and other common modules
Some of the groups are more about how modules are implemented, rather than how they are used, such as “Algorithms”. The distinction between data types and data structures is probably not clear for newcomers either (so that probably wouldn’t help them)
I do believe some groups are very useful though: “Processes” provide a nice way to group behaviours and process-related functionality which makes it easier to explore. For example, if someone is looking for a `gen_server`, it makes it more likely for them to learn about the `sys` module, which can be very useful. Groups for “niches”, such as “Code” and “Shell” are also good: if I am working with Erlang/AST, I can now quickly find the modules I care about. I remember in the past I had to click all of the modules in stdlib to find which one would help me manipulate AST, now I’d click around ~10.
Here is here an alternative of how one could organize `stdlib`:
Use groups more sparingly, focusing on how the modules are used. In particular, I kept groups for “COMPRESSION” and “IO” but those could be removed. One could also create a group for ets related functionality, which hosts ets/dets/digraph/qlc, but I am unconvinced
It is also worth having in mind that Erlang’s separation between `kernel` and `stdlib` make some of those groups naturally incomplete. For example, “IO” is missing the `file` module, “Code” is missing the `code` module. This was confusing in the old docs too and maybe there is something that could be done here…
For functions, depending on community feedback, it could initially focus on using groups only to separate deprecated functions. Elixir also uses them to separate what is a guard and what isn’t, and perhaps that could be done for `erlang` too, so the groups are mostly about how you use the functions (they are not exclusively for organization).
Advanced users, ^F you…” (j/k, couldn’t resist the pun 
)
