Features and UX discussion

[rcano]

Following @abgruszecki suggestion, I'm opening thread for discussion on the features and UX the scala 3 doctool should have.

The documentation tool is as important to a language as its collection api, and this will be reflected on all online documentation for scala 3 for years to come, so a process similar in importance to that of the collections strawman should take place.

[rcano]

My take on doctools: there are two kinds of documentation that I don't think should be mixed:

• Premier/Introduction to a library: this is text in prose, following a guide provided by the author that normally explains core concepts, structure and common patterns of the library. It's a piece of text that a new user reads, but then you don't frequently go back to it.
• Actual apidocs: this is the piece of documentation that you constantly go back to throught the lifetime of the library that you use. This text is heavily structured, not designed to be read like a book, but instead designed to answer quick questions when using a library, such as "what class provides this method?", "how do I get an instance of this type?", "what are the implementations of this type?".

Typically, for the first kind there's the library's webapge, which provides this introduction as well as link to the actual apidocs, while the apidocs are a published to maven and retrieved by IDEs, can be opened locally as well.

Both dottydoc and this tool focus too much on the first, which again, is only read at the beginning when you start using the library, but as you code you don't want this, and the fact that it's taking the center of attention of the apidocs is a waste of space and time since you have to dodge it everytime (as well as download it from maven). I feel that this doctool is trying to provide a website template engine, and I don't want that in my docs (note that this is different to a class or package documentation. I find it perfectly fine to find all relevant information on this, like java does, or scala-test).

Focusing on the apidocs part, I use this in two modes: question-answer, and exploring.
The first I think is nicely attented today by scaladoc, where the main concept of the page is the search bar. This is a great idea and should be expanded on, by allowing more than just literal text search across the index. I whish to ask "what methods return this type?", "what providers are there for this type class?", "how can I convert from this type to that type?"

For exploring, the traditional tree of package classes does a fairly okay job, but could be improved by adding implementations of a type, as descendants of that type's node

In general, I'd say scaladoc current UX reflects pretty much the right focus of attention

Some notes on the UX of current implementation of dottydoc and this tool: do not reload the page when clicking a link. I live in the southern hemisphere, far away from all your servers in north america and europe. Each time I click a link, the page goes blank because the browser is loading something new, and I have to wait 2-3 seconds as it loads, making me totally lose context and focus. The javadoc and scaladoc design using iframe works perfectly, I can keep browsing or reading what I currently have present, while I wait for the link I clicked to show up. This reloading ailment is exacerbated by the fact that even clicking a node on the tree (like a package) causes the entire page to be reloaded just for expanding that node.

Spacing is totally wrong, 90% of the page is just empty space, and the scrollbar becomes huge simply because there's endless whitespace in between lines.

[vivekragunathan]

If it isn't available already ... it would be nice to reference a function parameter in the documentation text (such that it is seen as a function parameter and picked up during refactoring and such)

/**
 * Adds one to the specified ???
 *
 * @param number given number to add 1 to
 * @return ??? incremented by 1
 **/
def addOne(number: Int): Int = ...

A way to specify number, say [[@param number]] or something like that.

[TheElectronWill]

Thanks for your feedback!

Each time I click a link, the page goes blank because the browser is loading something new, and I have to wait 2-3 seconds as it loads, making me totally lose context and focus. The javadoc and scaladoc design using iframe works perfectly, I can keep browsing or reading what I currently have present, while I wait for the link I clicked to show up. This reloading ailment is exacerbated by the fact that even clicking a node on the tree (like a package) causes the entire page to be reloaded just for expanding that node.

I think there are several issues here:

• Dokka generates many pages. Having one page per function (among others) may not be a good thing.
• The pages themselves could be more optimized. There are duplicated identical <svg> tags in every page, which the browser must therefore load every time.
• The left menu is made of links because packages themselves can be documented. To expand a package you can click on the arrow on the right. This won't cause any page load.

Javadoc and Scaladoc don't seem to do anything special here: no ajax, no iframes, just normal links. But those links often point to the same page. And the generated pages are smaller (in terms of bytes).

[rcano]

Javadoc and Scaladoc don't seem to do anything special here: no ajax, no iframes, just normal links. But those links often point to the same page. And the generated pages are smaller (in terms of bytes).

I know javadoc, when using the left frame, uses an iframe for the "center" where the page is actually rendered, this allows the tree to not be reloaded. For scaladoc I think you're right, I wonder what gave me that impression.

[TheElectronWill]

I know javadoc, when using the left frame, uses an iframe for the "center" where the page is actually rendered, this allows the tree to not be reloaded.

You're right. I didn't know about that feature! They are no longer generated by default on recent javadoc versions, that's a shame.

[abgruszecki]

It would be nice to reference a function parameter in the documentation text

I agree @vivekragunathan, I tried to do that a bunch of times when writing Scaladoc. If I remember correctly, IntelliJ understands such links and takes them into account when refactoring. I'll see about actually supporting them in the doctool.

[abgruszecki]

@rcano For the most part, I agree with how you think. I personally would say that there are three types of documentation - one is tutorials, second is concept documentation (or high-level documentation), third is API documentation. Those are different in their aims, but they all want similar features. What we're focusing on (what I'd like us to focus on) is adding support for concept documentation. Cats page is a good example of concept documentation. Note that it's not structured like a tutorial - it doesn't try to show you how to use functors, it only describes what they are. I don't think this kind of documentation is useful to beginners only - I'd also say this is the correct place to document relationships between high-level concepts in a codebase, and that is the sort of information one would like to have available together with the API docs. Also note that this doc really, really needs practically zero templating - you can see that this is basically a Markdown file + tree navigation. And if we already support writing doc comments in Markdown - how come we cannot also display a standalone Markdown file? I've written similar project documentation in the past and I've seen it happen time and time again in open source as well - there's a real need here, and the effort on our part to support such documentation is really minimal compared to the gains.

[rcano]

I think the concept documentation is still just the first kind of documentation I described, for some libraries it may be just a tutorial, for a library like cats you are documenting applied category theory, for Play you want a comprehensive explanation of the different parts from html to json handling. How involved or structured this documentations are depends on each library but they are still just webpages that you consult at the beginning and then as you've grasped the concepts you don't check again (this is true for that cats documentation as well, since the concepts explained in that link are not cats specific even), the fact that cats could make do with just some MD files is anecdotal. I still think this is best served by webpages no matter how simple it is to add to the tool that specific markdown case for cats. The way I see it it's a matter of design/concerns, not implementation difficulty; having this information displayed every time you consult the apidocs is the problem for me.
I'd also like to point out that of all the libraries, those that require such kind of documentation are by far the exception, and that's usually because they are some comprehensive framework, like cats, scalaz, shapeless (I wouldn't even name akka or reactive libraries here as I think those do fine with just apidocs). You can probably count them with the fingers of one hand, while every other library is fine with just apidocs

I believe we both have articulated our perspectives well enough (and thanks for that). I'd like to hear other people points of view on the subject.