Improve accessibility for the generated docs

[jquesada2016]

I am a dev who is visually impaired, and I find it a bit difficult to navigate modules sometimes. The primary issue is the lack of a summary of all available functions, type classes, and operators in a given modules' page.

It would be extremely helpful if docs could be generated with a summary of all available items for the given module off to the side, which one could use to quickly jump to any interested item. Something similar to what docs.rs uses to show off to the side is a good example. There are a couple of things that would go a long way to making this very useful.

Grouping

Grouping items by type class, operators, and functions, where each grouping has both indentation and spacing between groupings makes it easier to scan visually, and braille displays can likewise summarize.

Ordering

Type classes and function names should be sorted alphabetically in order to quickly jump to a given item easier. The items that are generated in the main part of the window, i.e. the docs as they currently are, should remain in the order they're defined in the source code, as they usually provide insites into the workings of the library.

[f-f]

Thanks for reporting this @jquesada2016! I will move this issue to the compiler repo, since that's the bit that generates the docs in the first place - Spago is just a thin layer that orchestrates the building of these

[rhendric]

The group and ordering parts of this proposal seem at odds with #2525, in which we intend to double-down on the author's preferred ordering of module contents by letting authors add section headers and such.

Would a richer sidebar offering a table of contents overview of the module's structure be useful to you if we kept the author's grouping and ordering instead of regrouping by language element type and alphabetizing?

[jquesada2016]

Sorry for the late reply, I didn't get a notification, and therefore missed your message.

What would the organization look like? I saw on the issue you mentioned, they had a link to this doc site.

In general, the problem with the current layout is that, for me, having tunnel vision, it's very difficult to tell where one item stops, and the next begins. Font, weight, spacing, and vertical margins play a role in this. Having a item table helps tremendously, especialy for infix operators that are generally horizontally very narrow, and are easy to miss.

The reason this helps is because I can skip all the text I'm not interested in, jump to the exact spot the docs of the item I'm interested begin, and then jump back up to the TOC to continue skimming. Having the TOC on the side independently of the main content scroll area helps to not visually lose your place when jumping around in the docs.

I suppose the primary question might be if the TOC should have a flat structure or a hierarchical layout...this I am not sure about, as there are advantages to both. I will briefly try and explore these two here.

Flat

Suppose we have items looking like this:

Type Classes

Class1
Class2

Type Synonyms

TypeA
TypeB

Data Types

[Great][#)
Awesome

Functions

myFn1
myFn2
myFn3
myFn4

Operators

[/](#)
/
*
/

I am inclined to believe that the more a user is familiar with a given librar, this form of quick reference hopping layout is more efficient, as there's generally less to remember iin terms of landmarks. If a user didn't know where a function is, they jump to the functions section, and read alphabetically the functions to quickly jump to where they're trying to go. This results in a very consistant experience going from one library to the next, not having to become familiar with the particular way an author organized their docs.

Author-organized Sections

This section assumes a somewhat similar layout to the docs linked above, and following somewha of a mark-down convention

• Introduction
  • Preface
  • About the Author
• Topic 1
  • Grouping 1
    • class Class1
    • function apple
    • function orange
    • operator (>=>)
• Topic 2
  • Grouping 1
    • class A
  • Grouping 2
    • function blah

In this TOC, it follows the documentation layout as organized by the author. If this were the first time a user came accross this library, or before they became familiar with it, then this layout would be fantastic, as it would allow a user to still find what they are looking for, but in a thematic fashion.

I have only two objections

1. Users are at the mercy of the organizational skills of the author
2. Going from one library to the next would have little to no consistency

Regarding 1, I suppose, is true in general about all docs, but here I am referring to the ability for a motor or visually impaired user to find what they are looking for without needing to dig around.

The second point, is probably the most impactful in the context of this conversation. Needing to reacquaint ones self with a different navigation layout for each library is akin to needing to learn a new website.

I generally like both, and there might be use in having both options, perhaps configurably so.

Let me know what your thoughts are.

[jquesada2016]

Also, just to clarify, this issue is only intended to be concerned with a TOC-type aid, not the actual documentation content itself.

[rhendric]

If I understand you correctly, your main argument seems to be that having an alphabetized list lets you quickly look up the name of a function you know and then navigate to its definition.

I'm curious under what circumstances you know the name of a function, are on the documentation page for that function's module, but don't have a link to its definition. If I'm curious about a function I encounter in code I'm reading or remember reading about at some point, my workflow is:

• Type the name (or, if I can't remember it exactly, part of the name) of the function in Pursuit
• Click a result, and now I'm at the definition of the function

If I'm already on Pursuit and I'm curious about a function I encounter there, my workflow is:

• Click the name of that function, and now I'm at the definition of the function

If I'm ‘digging’ in a Pursuit page, it's because I don't have the name of a function in mind—I have a general idea of what I hope to accomplish, or I'm trying to understand how the module works as a whole. For that purpose, scanning a list of functions grouped by theme or level-of-advanced-ness or something else would be more useful than an alphabetical list.

Can you help me understand how your experience is different?

---

As an aside:

In general, the problem with the current layout is that, for me, having tunnel vision, it's very difficult to tell where one item stops, and the next begins.

This seems like something we should improve regardless of what we do with a ToC. If you can provide any specific tips for formatting that would make this less difficult, that would be welcome.

[jquesada2016]

If I understand you correctly, your main argument seems to be that having an alphabetized list lets you quickly look up the name of a function you know and then navigate to its definition.

Not necessarily. I am not assuming I know the name of the function I want, rather, I know I am looking for a function, or a data type, or a type class, and I can, at a glance, visually or with a screen reader, look at only functions, or data types, or type classes. Alphabetical ordering would only be incidental, since when you group items by their type, they most likely would lose meaning in the ordering the original author intended them to have, so sorting alphabetically just reinforces this fact.

So in purescript:

class Apple where -- ...

foo :: forall a. a -> a
foo = identity

infix foo as ...

bar :: forall a b. a -> b -> a
bar = const

class Orange where -- ...

Would be arranged in the TOC like:

Type Classes

Apple
Orange

Functions

bar
foo

Operators

...

In the purescript source, foo and (...) were logically close to each other because the infix operator ... was defined in terms of foo, but when you group by item type, this meaning is lost, so sorting alphabetically is probably the most expected behavior. But the sorting order should be incidental and not matter too much. The important thing is to be able to quickly navigate between item types, which is currently where my largest struggle with the docs is.

Now, if we assume that I do know the name of the function, then having the TOC sorted alphabetically matters a whole lot. The reason for this is because, if I am looking for the function foo, and I am at the function a in the TOC, then there's only one logical conclusion, I have to scroll down, and thus will find the item much quicker.

For fully sighted users, peripheral vision is extremely powerful, as at a glance, your brain is able to get the gist of everything in your visual scope. However, for individuals using a screen reader, braille display, or just lacking periphery vision, you have to go one by one to read each item. If things aren't sorted, you must go top down or bottom up. When it's sorted, you can use binary search, as you would in a large dictionary. (and yes, binary search is something they teach visually impaired kids in school, fun fact)

I'm curious under what circumstances you know the name of a function, are on the documentation page for that function's module, but don't have a link to its definition. If I'm curious about a function I encounter in code I'm reading or remember reading about at some point, my workflow is:

Well, this scenario is very common for me. If I am on the module page where a function is defined, and I know the name of that function, then I have a couple workflow scenarios:

1. I can try to scroll up and down the page, praying I'm scrolling in the right direction, and that I am able to spot it
2. I can use the browser's search functionality, and hope the item name isn't too common on the page
3. I can search using the docs search functionality, and hope not too many modules have the same item name

Currently, my strategy is the jump by heading level until I hear the item I need, but it's quite slow, since I don't know if the item I'm looking for is above or below my current position.

If I'm ‘digging’ in a Pursuit page, it's because I don't have the name of a function in mind—I have a general idea of what I hope to accomplish, or I'm trying to understand how the module works as a whole. For that purpose, scanning a list of functions grouped by theme or level-of-advanced-ness or something else would be more useful than an alphabetical list.

This I agree 100%. I suppose we've discovered a general theme exploring this issue, in which there are two somewhat opposing scenarios:

1. The user doesn not know this library, and wants to discover it's API
2. The user is already familiar, and needs to navigate it efficiently

Can you help me understand how your experience is different?

Of course! Don't be afraid of asking me anything. I can not represent everyone with visual impairment, but have been around enough people, and being so myself, to get the gist of what generally works and what does not.

This seems like something we should improve regardless of what we do with a ToC. If you can provide any specific tips for formatting that would make this less difficult, that would be welcome.

Of course. I suppose the difficulty would be how to communicate these ideas, since markdown is quite limited here.

[jquesada2016]

Any further thoughts/updates on this?