docs.scala-lang
docs.scala-lang copied to clipboard
scala
The documentation is hidden
I didn't even know there is a real documentation for the functions, until I read a book which specifically mentioned the type-based search, which I attempted to locate, and struggled. The guide page about Type-Based search doesn't even try to explain how to get to the actual type-based search page. Not once does the page mention that you have to click "API" while on the "Learn" page and then select the library API version, you probably don't even care about.
In fact, I would expect to be able to get to the "real documentation" from the main page with one click. Why is it hidden like this, under ill-defined terms like "Learn" and "API"?
Okay, I can see now that there is in fact a button on the main page which does bring you to the API versions page, if you know it's there. I'm just wondering if there is a clearer way to describe it, and maybe to have it point to the latest version by default?
I always clicked the large button "Documentation" before, which brings the user a large selection of options, and the API description says "API documentation for every version of Scala", which is kind of meaningless unless you already know what the site means by API documentation (I would have expected it to have something to do with the compiler API).
I have a browser bookmark because going to the main page and trying to locate the link is way too much trouble.
https://www.scala-lang.org/api/current
Occasionally, something about coursier breaks, or I need a latest version to install, and I must locate that info again. Is it "getting started" (big button) or "Install" (small link)? The instructions are different. I'm avoiding the page with links to tar files. Oh, maybe the instructions are not different, they just look different in different contexts. (Also, my browser is running under Windows but I need to install on WSL, an extra complication for context.)
In short, I agree with the sentiment behind this ticket.
One must add that this is not an easy problem, and a lot of thought and work has gone into the current state of improvements.
@dolezvo1 instead of "API docs" on the homepage would it be better to say "Standard Library docs"?
I definitely feel like that would be more descriptive of the function it fulfils, but I admit I might be missing some context as to why it is currently called just "API docs".
The JDK lingo is "API Documentation". The "JDK Home" page at Oracle has a big link on the left for ease of navigation. (That includes various modules, including tools, because it is a "platform". Is Scala a platform? It offers a toolkit view of the ecosystem.)
Under the several rubrics, the link is under "Specifications" (and not "Language and Libraries").
As with the Scala home page, I have to know or vaguely recall what I'm looking, but it is more spare. The Scala page looks good and does some self-promotion, besides the hard work of providing salient links.
The API link at the bottom is https://www.scala-lang.org/api/current/index.html for sure. Oh the language spec link is still Scala 2.
At the top, LEARN and INSTALL are called DOCUMENTATION and DOWNLOAD elsewhere on the page (the button and at the bottom). Probably that contributes to the feeling that I must solve a word puzzle to reach my destination.
Edit: I would also vote for "Standard Library", since everyone calls it that, including the language specification.