-
Notifications
You must be signed in to change notification settings - Fork 563
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve accessibility for the generated docs #4519
Comments
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 |
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? |
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. FlatSuppose we have items looking like this: Type ClassesType SynonymsData Types[Great][#) FunctionsOperatorsI 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 SectionsThis section assumes a somewhat similar layout to the docs linked above, and following somewha of a mark-down convention
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
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. |
Also, just to clarify, this issue is only intended to be concerned with a TOC-type aid, not the actual documentation content itself. |
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:
If I'm already on Pursuit and I'm curious about a function I encounter there, my workflow is:
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:
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. |
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 ClassesFunctionsOperatorsIn the purescript source, 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 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)
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:
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.
This I agree 100%. I suppose we've discovered a general theme exploring this issue, in which there are two somewhat opposing scenarios:
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.
Of course. I suppose the difficulty would be how to communicate these ideas, since markdown is quite limited here. |
Any further thoughts/updates on this? |
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.
The text was updated successfully, but these errors were encountered: