Closed nvaccessAuto closed 3 years ago
Attachment nvda_glossary.t2t added by Bernd on 2010-12-19 18:31 Description: Glossary in t2t format
Attachment nvda_glossary.html added by Bernd on 2011-06-21 13:43 Description: compiled Glossary for NVDA
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.
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?
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.
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.
Note that sapi 4 can be installed on XP, also, I don't think nvda works any more on Windows 2000
Is this a recursive explanation? It seems not to really explain navigator to me, putting on my dense head here.
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.
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.
- 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.
- 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.
- 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.
Jaws, Window-eyes
Comment, Maybe this and display chain driver etc, could be linked.
yes, may be if this Glossary gets bigger.
- 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.
- 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.
- 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.
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.
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"
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.
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.
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?
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:
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.
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?
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.
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?
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
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.
I beg to differ with https://github.com/nvaccess/nvda/issues/189#issuecomment-511631899. I think the User Guide, even in its current state, does go above and beyond listing the names and locations of settings and keyboard shortcuts. Albeit briefly, it explains, among many other thins, what each NVDA setting does and how each NVDA feature works. But even if you dispute this characterization of the User Guide in its present form, a glossary of terms is just a list of definitions of key terms. This is direct, factual information as opposed to tutorial-styled instruction, and ought be given within the User Guide itself. Despite using NVDA for many, many years, I cannot claim to have a full understanding of terms like virtual buffer, system caret, review cursor, and navigator object. A glossary would be massively helpful for novice and intermediate users alike. On that point, I would vote to have it near the top rather than the bottom of the User Guide.
Sorry, I wasn't trying to argue against including a glossary of terms - I do think it's a good idea! One tricky part is working out where to include such a glossary, and when to link to it vs linking to a section of the user guide. For instance, from the original issue, "IAccessible2" and "Extended insert" are both good candidates for a glossary definition. Something like Object Presentation (Object presentation settings?) which is an NVDA feature or concept, I would like to that section of the user guide first. (Actually reading the original issue again, a lot of the terms mentioned in it are not (no longer?) mentioned in the User Guide. Whether that has been because the terminology has been cleaned up over the years, or just that it has evolved naturally I'm not sure.
In order to proceed with creating a glossary, the next step then, would probably be for someone to start working on a list of such terms to be included.
Actually after thinking more about this, I don' really know if it makes sense to include a glossary into NVDA. Because in the end we will end up with thousants of proposals for terms which should be included but are not really specific to NVDA. Most of the terms can be leasily found by searching on Google for them which is way more intuitive than looking into the user guide. The user guide itself already explains the terms and you can jump to them directly from the content page. Adding a glossary would just add lot of duplicate or even redundant explanations.
@Qchristensen maybe it makes more sense to include such a glossary with general windows and NVDA specific terms into the basic training module which can be bought on NV Access website. What do you think?
Here is a list of terms which I think is important for novice users:
@Adriani90 All I can tell you is that from my experience, it wasn't as easy or straight forward to Google these terms as you may think. Especially if you are an absolute accessibility novice who is using a screen reader for the first time. The issue with just leaving them within the section they belong to is that you'd have to know beforehand what section that term belongs to, and for an absolute beginner (or even beginner with a bit of experience) that is not as intuitive as you may think.
The glossary will probably always be redundant, that's sort of the point of a glossary, to collect in one spot all the terms unique to the thing. Including them in classes/teaching modules is a good idea, but it's also useful to have the glossary available at any time for those who need it at 2am and it can't wait until the next class, and even if the teaching module is available at any time, for the same reason I outlined above, the user would have to know what part of the module to look in for that term, which may not be self-evident.
@chogenkamp The Basic Training for NVDA module Adriani referred to is available from NV Access shop: https://www.nvaccess.org/shop/ - it's a downloadable text or audio book (or hardcopy Braille). Once someone has purchased it and knows how to open it, I wouldn't expect they'd have much more trouble finding the glossary in the material than in the User Guide. Certainly the terms Adriani has compiled are mostly Windows terms moreso than NVDA terms. My view is that the User Guide should contain how to use NVDA and its features NOT how to use (or an explanation of) Windows features - yes you definitely need to know how to get around Windows (and other programs you will use, like your browser, or Microsoft Office, etc) in order to be most effective, but that is where other resources, such as the training material, or other material from Microsoft or 3rd parties comes in.
Given @Qchristensen's comment above, I'd say let's close this issue for now. I think this remains NV Access's decision to include such terms in the training modules, it would be helpful in my opinion at least.
I don't think this issue should be closed just yet. In the list given in https://github.com/nvaccess/nvda/issues/189#issuecomment-671094882, there are terms like system focus, browse mode, child object, etc. which are critical to understanding how to use NVDA functionality like the review cursor, object navigation, and so on. However, there are not-so-relevant terms like context menu and address bar which are not uniquely relevant for screen reader users but are just generally helpful for any average computer user to know. I agree that more discussion is necessary to lay down clear criteria for the inclusion and exclusion of terms in this glossary, but discarding the idea altogether seems premature at this point. To be clear, even @Qchristensen agrees that a glossary would be useful to include in the NVDA User Guide as expressed in https://github.com/nvaccess/nvda/issues/189#issuecomment-657965612. Please reopen this ticket.
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