Initial eDocument Discussion

[Quin]

Great stuff, Robert! You actually did something that I had wondered about but wasn't entirely certain on, I noticed that EXPORT wasn't linked to but didn't know if that was on purpose or not and didn't pay it as much mind as I should've. Good stuff!

[Robert]

Great stuff, Robert! You actually did something that I had wondered about but wasn't entirely certain on, I noticed that EXPORT wasn't linked to but didn't know if that was on purpose or not and didn't pay it as much mind as I should've. Good stuff!

Thank you.

There are more keywords that are not hyperlinked but are HTML encoded as keywords. These omissions are mainly because there is nothing of substance to link them to in the Help file. There are probably other exceptions to what I just stated. Let me know if there is something specific.

I am aware that the Help file falls pathetically short of any national qualifications for Standards of Accessibility and the underlying HTML would not be allowed on government websites because of this shortcoming. Perhaps a move to a newer documentation format could be considered that could better fill the needs of persons with disabilities.

[Quin]

I am aware that the Help file falls pathetically short of any national qualifications for Standards of Accessibility and the underlying HTML would not be allowed on government websites because of this shortcoming. Perhaps a move to a newer documentation format could be considered that could better fill the needs of persons with disabilities.

Hi Robert,
I definitely appreciate the forethought here, but blind people actually tend to prefer CHM files for their portability, small file size, and ease of navigation with a screen reader. However, I do definitely think the semantic structure of the BCX documentation could be improved in places. For example putting many more headings above sections in documentation, e.g. make each function/macro/keyword/etc. be a heading instead of just a div/paragraph/whatever it currently is.
If you want more specifics I can provide you with some this weekend, I'm swamped a bit with exams until the end of this week. You can also look at the documentation for NVGT, an audiogame engine created by a close friend of mine that I've also contributed to for some ideas on how to make nice accessible documentation, at least for blind people. We publish the documentation in four formats, but the CHM is the only one that ships in the official Windows installer because it's the best one
Thanks a ton!

Edit: Also, don't get the wrong idea about the government and accessibility. They never really cared, and especially in recent weeks it's gotten even worse. I've found 7 links with the exact same label, "tab bar navigation item link" at the top of the FAFSA website when I was filling it out for my college...they don't care. The international standards themselves are good, but that doesn't mean they follow them.

[Robert]

I am aware that the Help file falls pathetically short of any national qualifications for Standards of Accessibility and the underlying HTML would not be allowed on government websites because of this shortcoming. Perhaps a move to a newer documentation format could be considered that could better fill the needs of persons with disabilities.

Hi Robert,
I definitely appreciate the forethought here, but blind people actually tend to prefer CHM files for their portability, small file size, and ease of navigation with a screen reader. However, I do definitely think the semantic structure of the BCX documentation could be improved in places. For example putting many more headings above sections in documentation, e.g. make each function/macro/keyword/etc. be a heading instead of just a div/paragraph/whatever it currently is.
If you want more specifics I can provide you with some this weekend, I'm swamped a bit with exams until the end of this week. You can also look at the documentation for NVGT, an audiogame engine created by a close friend of mine that I've also contributed to for some ideas on how to make nice accessible documentation, at least for blind people. We publish the documentation in four formats, but the CHM is the only one that ships in the official Windows installer because it's the best one
Thanks a ton!

Edit: Also, don't get the wrong idea about the government and accessibility. They never really cared, and especially in recent weeks it's gotten even worse. I've found 7 links with the exact same label, "tab bar navigation item link" at the top of the FAFSA website when I was filling it out for my college...they don't care. The international standards themselves are good, but that doesn't mean they follow them.

Hi Quin:

O.K. I shall revisit the semantic structure.

Initially, years ago, each function/macro/keyword was separated by headings, for example, <h1></h1> etc., but I did not like the appearance.

I will have another assessment of the layout and will have a look at the NVGT docs.

[Robert]

I am aware that the Help file falls pathetically short of any national qualifications for Standards of Accessibility and the underlying HTML would not be allowed on government websites because of this shortcoming. Perhaps a move to a newer documentation format could be considered that could better fill the needs of persons with disabilities.

Hi Robert,
I definitely appreciate the forethought here, but blind people actually tend to prefer CHM files for their portability, small file size, and ease of navigation with a screen reader. However, I do definitely think the semantic structure of the BCX documentation could be improved in places. For example putting many more headings above sections in documentation, e.g. make each function/macro/keyword/etc. be a heading instead of just a div/paragraph/whatever it currently is.
If you want more specifics I can provide you with some this weekend, I'm swamped a bit with exams until the end of this week. You can also look at the documentation for NVGT, an audiogame engine created by a close friend of mine that I've also contributed to for some ideas on how to make nice accessible documentation, at least for blind people. We publish the documentation in four formats, but the CHM is the only one that ships in the official Windows installer because it's the best one
Thanks a ton!

Edit: Also, don't get the wrong idea about the government and accessibility. They never really cared, and especially in recent weeks it's gotten even worse. I've found 7 links with the exact same label, "tab bar navigation item link" at the top of the FAFSA website when I was filling it out for my college...they don't care. The international standards themselves are good, but that doesn't mean they follow them.

Hi Quin:

O.K. I shall revisit the semantic structure.

Initially, years ago, each function/macro/keyword was separated by headings, for example, <h1></h1> etc., but I did not like the appearance.

I will have another assessment of the layout and will have a look at the NVGT docs.

Hi Quin:

I have a couple of questions for you.

1. Would a separate page for each function / statement / code block topic be helpful ? For example ABS and IABS are currently on one page. Would it be helpful to have them on separate pages ?

2. The current structure of a procedure section is generally

Title
Purpose
Syntax
Return Value
Parameters
Remarks
Example

Should there be a Keyboard TabStop at each of the above locations ?

[Quin]

Hi Quin:

I have a couple of questions for you.

1. Would a separate page for each function / statement / code block topic be helpful ? For example ABS and IABS are currently on one page. Would it be helpful to have them on separate pages ?

2. The current structure of a procedure section is generally

Title
Purpose
Syntax
Return Value
Parameters
Remarks
Example

Should there be a Keyboard TabStop at each of the above locations ?

Hi Robert,
1. Yes, I think this would certainly be helpful, for a few reasons. Firstly, it would make the pages load much quicker. This one might be unavoidable, but the variables section, for example, is quite large and takes a decent amount of time to load into the screen reader's virtual buffer, which also sometimes can make you not land where you're supposed to. It's very common that I'll click on a keyword in the list for a big section, press enter then f6, wait a second, then be at the top of the variables section and have to do a search.
2. This could also be quite helpful, yes, if you can manage it. I never would've thought of it, but that's very smart.
Thanks!

[dragon57]

I don't know if this would be helpful, but I find the help file for Autohotkey V1.x is formatted in such a way to be very helpful. One page per function makes more sense to me.

[Robert]

I don't know if this would be helpful, but I find the help file for Autohotkey V1.x is formatted in such a way to be very helpful. One page per function makes more sense to me.

Thanks for that, dragon57, I will have a look.

[Robert]

Hi Quin:

I have a couple of questions for you.

1. Would a separate page for each function / statement / code block topic be helpful ? For example ABS and IABS are currently on one page. Would it be helpful to have them on separate pages ?

2. The current structure of a procedure section is generally

Title
Purpose
Syntax
Return Value
Parameters
Remarks
Example

Should there be a Keyboard TabStop at each of the above locations ?

Hi Robert,
1. Yes, I think this would certainly be helpful, for a few reasons. Firstly, it would make the pages load much quicker. This one might be unavoidable, but the variables section, for example, is quite large and takes a decent amount of time to load into the screen reader's virtual buffer, which also sometimes can make you not land where you're supposed to. It's very common that I'll click on a keyword in the list for a big section, press enter then f6, wait a second, then be at the top of the variables section and have to do a search.
2. This could also be quite helpful, yes, if you can manage it. I never would've thought of it, but that's very smart.
Thanks!

Hi Quin:

I just tried out NVDA Tab keyboarding with the BCX Help file. Uh, yeah, well, what can I say ?

Obviously, the keyword hyperlinks are a major impediment to navigation.

HTML 5 is not supported by .chm files so the semantic elements

<article>
<aside>
<details>
<figcaption>
<figure>
<footer>
<header>
<main>
<mark>
<nav>
<section>
<summary>
<time>

are not available to mitigate the navigation difficulties.

Perhaps, a separate BCX Help file mimicking the NVGT Documentation would be the best solution.

What do you think ?

If you are interested and have time to guide the project let me know. 

[Quin]

Hi Robert,
Yes, this would be amazing, and I would definitely be interested in helping with it! Just let me know what needs done! :_

[Robert]

Hi Robert,
Yes, this would be amazing, and I would definitely be interested in helping with it! Just let me know what needs done! :_

Very Good !

Please explain to me the keystrokes that you use to locate, in the NVGT Documentation .chm file index, the "Building NVGT For Linux" entry and then explain the keystrokes used to navigate through all the content on that page.

[Quin]

Hi Robert,
Okay, after opening the CHM, I land on a tree view right away. I use the down arrow key to navigate down until I hear

Advanced Topics for C++ Developers  collapsed  4 of 5  level 1\

I then press right arrow to "expand" this node, and keep pressing the down arrow. I press it a few times, until I hear:

Building NVGT For Linux  2 of 6  level 2

From there, I press enter to select the topic, then f6 to actually pull it up in the web view.
After that, I just use standard screen reader navigation commands. For me personally, I go through all the types of headings at once by repeatedly pressing H or Shift+H until I hear what I want, then I read from there. If I'm looking for something that's a link or something else more specific like that, I'll use K and Shift+K.
(FYI, my screen reader is NVDA).
Let me know if you need any more, I'm happy to provide!

[Robert]

Hi Robert,
Okay, after opening the CHM, I land on a tree view right away. I use the down arrow key to navigate down until I hear

Advanced Topics for C++ Developers  collapsed  4 of 5  level 1\

I then press right arrow to "expand" this node, and keep pressing the down arrow. I press it a few times, until I hear:

Building NVGT For Linux  2 of 6  level 2

From there, I press enter to select the topic, then f6 to actually pull it up in the web view.
After that, I just use standard screen reader navigation commands. For me personally, I go through all the types of headings at once by repeatedly pressing H or Shift+H until I hear what I want, then I read from there. If I'm looking for something that's a link or something else more specific like that, I'll use K and Shift+K.
(FYI, my screen reader is NVDA).
Let me know if you need any more, I'm happy to provide!

Hi Quin:

O.K. that info is a big help.
What's the difference between pressing H and Shift H ?

I'm going to think on this for a while.
I want to do this efficiently.
Translation: ?
"I'm lazy and want to do as little work as possible."

[Robert]

Hi Robert,
Okay, after opening the CHM, I land on a tree view right away. I use the down arrow key to navigate down until I hear

Advanced Topics for C++ Developers  collapsed  4 of 5  level 1\

I then press right arrow to "expand" this node, and keep pressing the down arrow. I press it a few times, until I hear:

Building NVGT For Linux  2 of 6  level 2

From there, I press enter to select the topic, then f6 to actually pull it up in the web view.
After that, I just use standard screen reader navigation commands. For me personally, I go through all the types of headings at once by repeatedly pressing H or Shift+H until I hear what I want, then I read from there. If I'm looking for something that's a link or something else more specific like that, I'll use K and Shift+K.
(FYI, my screen reader is NVDA).
Let me know if you need any more, I'm happy to provide!

Hi Quin:

O.K. that info is a big help.
What's the difference between pressing H and Shift H ?

I'm going to think on this for a while.
I want to do this efficiently.
Translation: ?
"I'm lazy and want to do as little work as possible."

Hi Quin:

I asked you "What's the difference between pressing H and Shift H ?"
I found the answer in the NVDA User Guide Section 2.3.8 Web Navigation.

Now to figure out what works without HTML 5.

[Quin]

Hi Robert,
It sounds like you've already found the information, but I'll put it here for integrities sake too:
When on a web page, we screen reader users have many commands to navigate between different elements. H goes through any type of heading, I goes through list items, l goes through lists, etc. However, just pressing these letters moves you forward through the document. if you want to go backwards through the same type of element, you add shift. Similar to how f3/shiftt+f3 are find previous/find next commands.
Let me know if you need any more info, I'm happy to help and have more free time on my hands right now than I probably should !