Skip to content
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

Usability: terminology dictionary needed? #189

Open
nvaccessAuto opened this issue Jan 1, 2010 · 19 comments

Comments

Projects
None yet
5 participants
@nvaccessAuto
Copy link

commented Jan 1, 2010

Reported by healeym on 2008-10-04 09:56
In case anyone thinks the following is an attack on their 'baby', let me say in advance that I think NVDA is very good already, and its Help/Documentation is far superior to System Access's (for example)! I hope I'm not viewed as sniping from the sidelines, but as passing on an authentic beginner's view which NVDA-experienced people would not usually have.

As the sighted husband of new user of NVDA I find that the documentation assumes my wife is already familiar with NVDA's terminology! Alternatively, it assumes that she's probably familar with another screen reader such as Jaws or Window-Eyes. These terms are probably so familiar to NVDA developers that they can't imagine any potential NVDA users not knowing them! The following terms are sometimes explained in passing, sometimes not. Definitions would be useful even where they might seem 'obvious' - people's ideas of what even a 'simple' term encompasses do vary a lot!
I'm not sure how the info should be presented - maybe via tooltips or links.
Here are some of the terms that my wife was thrown by - and understandably so, in my opinion! Some are NVDA-specific, some not, but a beginning user isn't going to care about the difference. It's not a huge list, so perhaps the work involved in supplying useful definitions is not huge either.

Here goes:

SAPI4
SAPI5
Virtual buffer
Old virtual buffer, new virtual buffer
Filtering
MSAA
Iaccessible2
Video intercept driver
Display hook
Jaws
Window-Eyes
extended Insert
Object presentation
Focus
Foreground window
Object
Navigator object
Edit cursor
Review cursor
System caret
Dynamic content
Field (is this the same as Object?)
Form field

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Jan 1, 2010

Comment 1 by Bernd on 2008-11-02 01:22
Should the words above may defined in the user guide? That will be the easiest way because there is no code to change.

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Apr 4, 2010

Comment 2 by Bernd on 2010-04-04 16:47
At the moment I'm translating a german Glossary in English. Should this be integrated in the User Guide or should I implement it on the Wiki?

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Dec 19, 2010

Attachment nvda_glossary.t2t added by Bernd on 2010-12-19 18:31
Description:
Glossary in t2t format

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Dec 19, 2010

Comment 3 by Bernd on 2010-12-19 18:37
I and two German people wrote a therminology dictionary which I've just uploaded. Users can try the Glossary in html format and say how it is.
Jamie and Mick: Please consider implementing it somewhere in the wiki or perhaps in the user guide. It will answer many user questions.

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Dec 20, 2010

Comment 4 by briang1 on 2010-12-20 12:16

Hi, I have changed and added comments below. See what you think anyway.

NVDA Glossary
Version 1.0
last Update: 19.12.2010

Table of contents
• 1. sapi Might be an idea to extend this to API or add an extra one for that to start with.

• 2. virtual buffer
• 3. MSAA
• 4. UIA Explain UI as well, before using it.
• 5. iaccessible
• 6. Video interceptor Not sure why we talk about this one really.
• 7. display hook
• 8. Jaws, Window-eyes
• 9. extended insert
• 10. object presentation
• 11. Focus
• 12. Foreground window
• 13. Object
• 14. Navigator, Navigator Object
• 15. Review cursor, System Cursor
• 16. Dynamic content
• 17. field
• 18. Form Fields
• 19. alternate navigating with the windows keyboard mouse

You need to add carat and its meaning in the computer sense I feel.

  1. sapi
    The Speech Application Programming Interface or SAPI is an API developed by Microsoft to allow the use of speech synthesisers made by different manufacturers. The folowing table shows all Windowsversions supported by NVDA and which sapi versions they include:
    Windows version
    Sapi Version
    Windows 2000
    Sapi 4
    Windows xp
    Sapi 5
    Windows Vista
    Sapi 5.1
    Windows 7
    Sapi 5.1

Note that sapi 4 can be installed on XP, also, I don't think nvda works any more on Windows 2000
2. virtual buffer
Virtual Buffers are used to present complex documents in NVDA and other screen readers. Elements such as headings, paragraphs, tables and lists will be represented in such virtual Buffers. Buffers are named virtual because information about the object is only presented by the Screen reader and not on the screen. Examples of documents accessed by virtual buffers are HTML files in Firefox, Google Chrome, Internet explorer and the windows help (winhlp32) or reading PDFs in Adobe Reader. NVDA has been changed a lot since its inception, and this will continue, so in the changes document you will read about old and new virtual buffers.

  1. MSAA
    Maybe AT needs an entry??
    Microsoft Active Accessibility (MSAA) is an Application Programming Interface (API) for user interface accessibility. MSAA is designed to help Assistive Technology (AT) products with interact with standard and custom user interface (UI) elements of an application (or the operating system), as well as to access, identify, and manipulate an application's UI elements. AT products work with MSAA enabled applications in order to provide better access for individuals who have cognitive difficulties, impairments, or disabilities. One example of AT products are screen readers for users with limited sight,.
    The above sounds like it should be at the start of any explanitory text, as it covers a number of abbreviations not in the list itself.
  2. UIA
    User Information Automation is the further development of MSAA. There are interfaces between them.
    Or did you mean with both of them?
  3. iaccessible
    iaccessible is an accessibillity interface for Windows systems developed by IBM. IA2 is an alternative to the MSAA successor UI Automation
    Kind of leaves the question, why? grin
  4. Video interceptor
    A video interceptor works like a driver that catches all information provided by the display card and passes all of it to a program like a screen reader, So the screen reader is able to present the data to the user which would otherwise only exist on the screen. This enables the user to activate an object without knowing where it is in the hirarchical order or if the object isn't detected by the APIs. The disadvantage of this is that video interceptors must be installed with administrator privileges. This makes a portable screenreader impossible.
  5. display hook
    This is a method to get information written to the screen without installing a display driver to the system. For example: the windows screen reader, System Access, NVDA, and in the Orca screen reader for linux packaged with gnome. This method does have limitations though.
  6. Jaws, Window-eyes
    These are two examples of commercial screen readers. The developers of these commercial products differ in their implimentation, but their goal is the same.����
    Comment, Maybe this and display chain driver etc, could be linked.
  7. extended insert
    Modern keyboards have got between the normal keyboard and the numberpad an extended block. In this block you'll find 4 arrow keys at the bottom, and at the top is a block of 6 keys: Insert, delete, home, end, page up and page down. All of them can be found on the number pad, too. So there has to be a way to differenciate the keys on the numberpad from the extended pad. So, For example: If you want to make clear that the insert key on the extended pad is meant, you will say "extended insert".
  8. object presentation
    these settings change nvda's verbosity while reading objects. Here you can tell nvda (not) to read the type of an object or the position inside a list box.
  9. Focus
    If you are working in windows allways one object has the focus. This could be an edit field, a combo box, a checkbox etc.
  10. Foreground window
    This is the window you work in. If you read this document, the foreground window is your Internet browser probably.
  11. Object
    Objects are everything which can be shown on the screen. Objects are for example edit fields, buttons, checkboxes, program windows, etc.
    Are links objects as well. Sounds silly but I get the question all the time!
  12. Navigator, Navigator Object
    the navigator implements a method for moving between objects inside an application. the current navigator object is the object which is displayed in the navigator.

Is this a recursive explanation? It seems not to really explain navigator to me, putting on my dense head here.

  1. Review cursor, System Cursor
    You maybe need to reverse these as the explanation is the other way around for clarity.

The insertion pointer in an edit field is called the 'system cursor' because it can be moved with windows' built-in tools (arrow keys, page up, page down etc. These are purely windows functions.
the review cursor is an nvda internal cursor. The user can navigate inside an object and read its content without moving the system cursor. This may or may not be actually visible on screen.

  1. Dynamic content
    In the last few years webdisigners built dynamic content into their websites. This means that particular parts of the site get updates without reloading the whole site. I.E. Ebay auctions and share prices.
    Should this not be pages rather than web site?
  2. field
    All objects not known by NVDA are named field.
    What about Pane though?
  3. Form Fields
    all editable objects within a web page (check boxes, combo boxes, edit fields, buttons) are summarized by this term.
  4. alternate navigating with the windows keyboard mouse
    This is a Windows facility.
    With this function it is easier to move the mouse along axes of coordinates
    After pressing the shortcut key alt+shift+numlock, a message box comes up to inform you that you are about to enable the keyboard mouse. Now you can:
    • click "ok" to enable the keyboard mouse
    • click "cancel" to keep it disabled, or
    • click "settings" to open the 'keyboard mouse' tab of the control panel's accessibility dialog box.
    When the keyboard mouse is enabled, you can use the following numpad keys to move the mouse pointer in the given direction:
    • Numpad 7: To the top left corner.
    • Numpad 8: To the top
    • Numpad 9: To the top left corner
    • Numpad 4: To the left side
    • Numpad 6: To the right side
    • Numpad 1: To the bottom left Corner
    • Numpad 2: To the bottom
    • Numpad 3: Bottom rightTo the bcorner
    you can speed up the mouse pointer movement by using the numpad keys together with the ctrl key. Using them together with the shift key will slow down the mouse pointer movement.
    Does this not belong in the user manual?
    To get braille output while using the keyboard mouse, the following 3 conditions must be met:
    • you have to enable mouse tracking in the mouse settings dialog.
    • the braille display has to be tethered to the review cursor
    • the "follow mouse Pointer" in the review cursor settings dialog has to be checked.
    OK, just a few alterations comments and suggestions. I don't have the time just now to learn the text format, but anyway, these are just suggestions and observations.
@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Jun 21, 2011

Comment 5 by Bernd (in reply to comment 4) on 2011-06-21 13:38
Replying to briang1:

Hi, I have changed and added comments below. See what you think anyway.

thanks I'll explain our thaughts shortly but not all. Some of your thaughts are allready implemented in the glossary. I'll attach the modified version shortly.

• 1. sapi Might be an idea to extend this to API or add an extra one for that to start with.

thanks, will be in the next version.

Note that sapi 4 can be installed on XP,

yes, but this table shows only, which version of sapi is include in which version of windows.

• 6. Video interceptor Not sure why we talk about this one really.

We want to explain it so other users understand why the devs don't include it.

also, I don't think nvda works any more on Windows 2000

A german user told us that NVDA worked under windows 2000 so we mention it. Even it isn't supported by NVDA officially.

  1. MSAA

Maybe AT needs an entry??

Yes, needs to be done.

The above sounds like it should be at the start of any explanitory text, as it covers a number of abbreviations not in the list itself.

yes, that's right.

  1. UIA

User Information Automation is the further development of MSAA. There are interfaces between them.

Or did you mean with both of them?

no, MSAA and UIA are to diffrent thinks but NVDA works with both of them.

  1. iaccessible

iaccessible is an accessibillity interface for Windows systems developed by IBM. IA2 is an alternative to the MSAA successor UI Automation

Kind of leaves the question, why? grin

As I understand IA2 is more useful and provides more features than MSAA and UIA.

  1. Jaws, Window-eyes

    Comment, Maybe this and display chain driver etc, could be linked.

yes, may be if this Glossary gets bigger.

  1. Object

Are links objects as well. Sounds silly but I get the question all the time!

I think yes because you can jump on it using object navigation and interact with Links.

  1. Navigator, Navigator Object

Is this a recursive explanation? It seems not to really explain navigator to me, putting on my dense head here.

yes, needs to be done.

  1. alternate navigating with the windows keyboard mouse

This is a Windows facility.

Yes, but works great with nvda.

Does this not belong in the user manual?

Hmm, this needs to be considered by the developers as it is really a windows feature. Maybe the devs could note it in the user guide.

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Jun 21, 2011

Attachment nvda_glossary.html added by Bernd on 2011-06-21 13:43
Description:
compiled Glossary for NVDA

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Jun 21, 2011

Comment 6 by briang1 on 2011-06-21 18:22
Just a thought, in XP the update to UIA is an optional windows update, but recent experience has shown it to be buggy and slow, so the devs have elected to turn it off in XP even if its installed. Not looked at current manual, so might be in there.

As regards Windows 2000l, I understood it threw a lot of errors, but I cannot test it, as even my clunkers don't go back that for!

There was a recent query on one of the lists about the mouse and I and others mentioned mouse keys. I agree they work well. I notice that other screenreader makers have no qualms about mentioning windows keys where applicable, usually mentioning they are in fact part of Windows, but I often feel the average person does not care where they are defined, only what they do!
IE its only us who are pedantic about such things.
It might be worth re mentioning the reason why the copy and paste are only announced in the places they are.

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Jun 21, 2011

Comment 7 by jteh on 2011-06-21 22:24
It'd be great if you could look through the current User Guide to determine whether this glossary is really necessary. Recently, I've tried to clarify a lot of these terms (and link to relevant sections when appropriate) in the actual text. For example, system focus, system caret, object, etc. are all explained at the top of their respective sections and are linked when referenced.

It's true that IAccessible2, etc. aren't explained, but these terms are isolated to one line:

•Support for common accessibility interfaces such as Microsoft Active Accessibility, Java Access Bridge, IAccessible2 and UI Automation

This is only relevant to the user in that if an application says it supports one of these, it will generally work. Beyond this, it is technical info and the user need not be concerned with it. Perhaps we could clarify it like this: "Support for common accessibility interfaces for making applications accessible"

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Jun 22, 2011

Comment 8 by briang1 on 2011-06-22 07:36
Well, what is really needed is someone relatively new to look and see. For a start there have been many changes and additions to the manual, and trying to figure out if we might be duplicating something already well explained is going to be time consuming and a bit like trying to catalogue something which is being changed real time.
However some things have raised queries in my mind, notably those associated with Java Access bridge versions and nvda support, and the need to reinstall if a java application is altered or updated.
The 64bit aspect of a lot of things is also hazy to me, if I turn my brain off so to speak. its hard to put oneself in the position of a new user.
Incidentally are you aware that someone on the freelists group has been using robobraille to make daisy versions of the manual? This sounds like a good idea as it is sometimes better to get info in audio than relying on the text.

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Jun 22, 2011

Comment 9 by jteh (in reply to comment 8) on 2011-06-22 09:00
Replying to briang1:

However some things have raised queries in my mind, notably those associated with Java Access bridge versions and nvda support, and the need to reinstall if a java application is altered or updated.

This is not really relevant to NVDA's own documentation, but rather, it is specific to Java. The Java Access Bridge documentation is hopeless (and the new version doesn't even have an installer), so we might need to provide some supplemental documentation, but it doesn't belong within NVDA itself.

The 64bit aspect of a lot of things is also hazy to me

Generally, there should be no difference on a 64 bit system as far as the average user is concerned. Where there are problems, this is generally a bug.

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Sep 8, 2011

Comment 10 by Bernd on 2011-09-08 08:23
@jcsteh: ok I think a few things could be removed from the glossary. What about noting the keyboard mouse feature of windows in the user guide? Maybe we could have a beginners documentation where such things are listed?

@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Nov 12, 2013

Comment 11 by nvdakor on 2013-11-12 05:04
Hi,
Quite an old ticket, but since we have a lot of changes since then, I'd like to add some additional comments:

  • We have tutorials designed for beginners now, so I think that oculd solve some of the problems raised in this ticket.
  • I do understand that some parts of the user guide is not user-centric or not understandable for a new user. I think a gradual editing could detect this problem in the end.
    Thanks.
@nvaccessAuto

This comment has been minimized.

Copy link
Author

commented Oct 2, 2014

Comment 12 by blindbhavya on 2014-10-02 09:37
Hi.
'• I do understand that some parts of the user guide is not user-centric or not understandable for a new user. I think a gradual editing could detect this problem in the end. '
I agree. I don't yet completely understand the review modes, system focus and system caret, object navigation and a few other things. Could you have a look at its documentation and see if there is anything you could add/modify that would make it easier to understand for a non tech-savey user?
I won't be able to explain in detail which parts of the documentation I didn't understand right now.
But I would be willing to comment on any improvements you may make.

@leonardder

This comment has been minimized.

Copy link
Collaborator

commented Jul 18, 2017

CC @josephsl @jcsteh @bdorer

@Qchristensen: Since you are now involved with the NVDA training materials, you might also want to share you ideas about this issue?

@chogenkamp

This comment has been minimized.

Copy link

commented Jul 9, 2019

I know this is an old issue, but I just wanted to say that I am in the middle of trying to prepare some training materials for my coworkers to train them in how to use NVDA and it would be absolutely helpful to have a glossary/primer of the very basic terms, like caret, focus, object, etc. These terms are indeed part of the documentation but as they are part of the actual sections, it's easy to miss the definition if you don't happen to read all of the section where it is contained, and the documentation itself is dense so sometimes I find myself skimming, trying to find a particular instruction or shortcut key. I think a separate glossary would be a very helpful reference to have, especially for those that screen readers in general are a new thing (ie fully-sighted users who are learning it for a friend/loved one, or to use professionally to test websites, etc) and are not familiar with the elements involved. So that's my two cents, whatever they may be worth! Best of luck with NVDA development.

@Adriani90

This comment has been minimized.

Copy link
Collaborator

commented Jul 9, 2019

I am thinking how to implement this so it is most convenient for all people. What do you think if we create a table at the end of the userguide containing all relevant terminologies with their description? I could create one.
Or is it prefered to have a glossar as a Wiki here on github?

@chogenkamp

This comment has been minimized.

Copy link

commented Jul 9, 2019

Woo hoo a reply!

So right now there is this page: https://www.nvaccess.org/files/nvdaTracAttachments/189/nvda_glossary.html

It could be updated (and categories could be created to place the current terms on there, which are sort of randomly listed) and linked both from the GH page and also at the start of the documentation page. Link it in as many places as you can, so people have more of a chance to find it no matter where on the NVDA site they are.

The glossary page could be organized similiarly to this page, re: numbering and categories: https://www.nvaccess.org/files/nvdaTracAttachments/455/keycommands%20with%20laptop%20keyboard%20layout.html

@Qchristensen

This comment has been minimized.

Copy link

commented Jul 16, 2019

Chiming in late here (not sure how I missed being tagged in this one back in 2017, but I'm here now :)

I'd mostly add that the User Guide is not specifically designed as a tool to teach new users to use NVDA, but moreso as a reference to confirm the keystroke for a function or where a setting is etc. We now have the training material which is designed to teach a new user all the intricacies of NVDA, Windows and Office: https://www.nvaccess.org/shop/

All of which is not to take away from improving the other documentation or creating a comprehensive glossary of terms - simply to add that for the use case of the original poster, the training material would be better placed now to meet that specific need.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.