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.

Sign up for GitHub

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

Jump to bottom

Add section on add-on store to the Quick Start Guide in the User Guide #16486

Closed
wants to merge 12 commits into from
Closed

Add section on add-on store to the Quick Start Guide in the User Guide #16486

Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
b9b3dce
Update userGuide.t2t
Qchristensen May 6, 2024
08b46f9
Update user_docs/en/userGuide.t2t
Qchristensen May 6, 2024
40c359a
Update user_docs/en/userGuide.t2t
Qchristensen May 6, 2024
ee4a5f0
Update user_docs/en/userGuide.t2t
Qchristensen May 6, 2024
6187db4
Update user_docs/en/userGuide.t2t
Qchristensen May 6, 2024
80ec23f
Update user_docs/en/userGuide.t2t
Qchristensen May 6, 2024
343f613
Update user_docs/en/userGuide.t2t
Qchristensen May 6, 2024
954c03d
Update user_docs/en/userGuide.t2t
Qchristensen May 7, 2024
301761c
Update user_docs/en/userGuide.t2t
Qchristensen May 7, 2024
ad683a2
Update user_docs/en/userGuide.t2t
Qchristensen May 7, 2024
b72f7a1
Update user_docs/en/userGuide.t2t
Qchristensen May 9, 2024
c3d69fd
Update user_docs/en/userGuide.t2t
Qchristensen May 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions user_docs/en/userGuide.t2t
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,64 @@ To open NVDA's menu, press ``NVDA+n``.
To open NVDA's general settings dialog directly, press ``NVDA+control+g``.
Many settings screens have keystrokes to open them directly, such as ``NVDA+control+s`` for synthesizer, or ``NVDA+control+v`` for other voice options.

++ Add-ons ++[Addons]
Add-ons are like small programs which provide new or changed functionality for NVDA.
Qchristensen marked this conversation as resolved.
Show resolved Hide resolved
Add-ons are developed by the NVDA community, or external companies.
Qchristensen marked this conversation as resolved.
Show resolved Hide resolved
As with any software, it is important to be confident in the developer of an add-on before using it.
Qchristensen marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
As with any software, it is important to be confident in the developer of an add-on before using it.
As with any software, it is important to be confident in the developer of an add-on before using it.
You can do this by researching their reputation (eg. how long have they been contributing, look for user feedback in the NVDA user or add-on groups), verifying that the add-on is regularly updated, and seeking community feedback through the forums or social media.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably mention the "Community reviews" here?

I'm also not sure we should add too much more here when we don't actually mention this in 13.2 - perhaps we should expand on this in 13.2 and add a brief mention here that "As with any software, it is important to be confident in the developer of an add-on before using it. Section 13.2.1 contains tips on researching add-ons and authors, such as community reviews"?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That sounds like a better solution.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have created PR #16510 to add @gerald-hartig's suggestions to the main add-on section. I'd like to propose that PR be accepted at the same time or before this one, so the following makes sense:

Suggested change
As with any software, it is important to be confident in the developer of an add-on before using it.
As with any software, it is important to be confident in the developer of an add-on before using it.
Please refer to [Installing Add-ons #AddonStoreInstalling] for ways to verify add-ons prior to installation.

The "Add-ons and the Add-on Store" section of the user guide contains information about every feature of the add-on store.
Qchristensen marked this conversation as resolved.
Show resolved Hide resolved

The add-on store is available from the Tools menu.
Qchristensen marked this conversation as resolved.
Show resolved Hide resolved
Press ``NVDA+n`` to open the NVDA menu, then ``t`` for tools, then ``a`` for add-on store.
When the add-on store opens, it shows "Available add-ons" if no add-ons are installed.
When add-ons are installed, the focus starts in the "Installed add-ons" tab when the add-on store opens.
Qchristensen marked this conversation as resolved.
Show resolved Hide resolved

+++ Available add-ons +++[AvailableAddons]
When the window first opens, add-ons may take a few seconds to load.
NVDA will read the name of the first add-on once the list of add-ons finishes loading.
Available add-ons are listed alphabetically in a grid.
Use the ``arrow keys`` or press the first letter of an add-on name to move around the list.
Press ``tab`` once to move to a description of the currently selected add-on.
Use the reading or ``arrow keys`` to read the full description.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not familiar with the term reading here, is it something we use in the rest of the docs?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't give instructions like this through most of the user guide (that's more a training module area). I feel saying something like this is needed here until #16485 is implemented (if that were implemented, I think we could drop this line). In the meantime, I've suggested"reading text" which links to the quick start guide topic of that name - https://www.nvaccess.org/files/nvda/documentation/userGuide.html#ReadingText Otherwise we could say "Use the Say all, or navigation keys"?

Suggested change
Use the reading or ``arrow keys`` to read the full description.
Use the [reading text #ReadingText] or ``arrow keys`` to read the full description.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Qchristensen I'm not sure "use the reading text" makes sense. It's like "Use the force", without there being a force. :-)

I get that you mean it to be read "Use the reading text keys, or the arrow keys", but even that sounds awkward since "reading text keys" aren't a thing.
"reading keys", okay, as a general shorthand for "review or object nav keys", but "reading text keys"? Hmmm.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like an excuse to write "Use the force" in the user guide somewhere! Happy to accept a change here - I was originally thinking of saying use "Say all", but that is just one of any number of keys you COULD use to read text with. I don't think there are (many, or any?) other examples of this kind of instruction in the User Guide, as it's not how it is written. If we could have NVDA read that whole text field on focus it would negate the need to give any specific instruction here :) I wasn't keen to leave it unsaid though as it is easy to get to that description field, have it read one line and not know whether there is more or that you need to specifically read it if there is.

I just had a look in Basic Training and I mention "Reading keys" or "Reading and navigation keys" in a couple of places.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps this is more of a discussion for #16485 but for me NVDA reports that this field is multiline, which pretty clearly indicates there may be more than one line there. Why it is a problem in the add-on store specifically and not in many other places - when tabbing into an multiline edit field on web pages for example?

Press ``tab`` to the "Actions" button, which can be used to install the add-on, among other actions.
Press ``tab`` to "Other Details", which lists details such as the publisher, version and homepage.
To return to the list of add-ons, press ``alt+a``, or ``shift+tab`` back to the "Available add-ons" list.

+++ Searching for add-ons +++[SearchingForAddons]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section seems more or less identical to AddonStoreFilterSearch, perhaps it's just worth moving that section here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar, but I think worth mentioning in both places - in fact, there shouldn't be much in the quick start guide which ISN'T replicated elsewhere, albeit reworded.

As well as browsing all available add-ons, it is possible to filter the add-ons shown.
To search, press ``alt+s`` to jump to the "search" field and type the text to search for.
The list changes while typing the search, once done, press ``tab`` to go to the filtered list of add-ons.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be worth mentioning what fields you can search by (add-on ID, display name, publisher, author or description)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The list changes while typing the search, once done, press ``tab`` to go to the filtered list of add-ons.
The search field can contain information including the add-on ID, display name, publisher, author or description.
The list changes while typing the search, once done, press ``tab`` to go to the filtered list of add-ons.


+++ Installing add-ons +++[InstallingAddons]
With the focus on an add-on you would like to install, press ``enter``.
The actions menu opens with a list of options.
These actions include: "Install", "Home page", "License", "Source code", "Community reviews".
To install the add-on, press ``i`` or ``down arrow`` to "install" and press ``enter``.
The focus returns to the add-on in the list and NVDA will read the details about the add-on.
The "Status" information reported by NVDA changes from "Available" to "Downloading".
Once the add-on has finished downloading, it will change to "Downloaded. Pending install".
Repeat with any other add-ons you would like to install at the same time.
Once finished, press ``tab`` until the focus is on the "Close" button, then press ``enter``.
A dialog appears advising that changes were made, and you must restart NVDA.
Press ``enter`` to restart NVDA.

+++ Browsing installed add-ons +++[BrowsingInstalledAddons]
Qchristensen marked this conversation as resolved.
Show resolved Hide resolved
Press ``alt+tab`` to move between the tabs or sections of the add-on store.
Qchristensen marked this conversation as resolved.
Show resolved Hide resolved
The tabs include: "Installed add-ons", "Updatable add-ons", "Available add-ons" and "Installed incompatible add-ons".
Each of the tabs is set out the same as the "Available add-ons" tab.
Qchristensen marked this conversation as resolved.
Show resolved Hide resolved
The actions menu of installed add-ons includes "Disable", and "Remove" rather than "Install".
Disabling an add-on stops NVDA from loading it, but leaves it installed.
To re-enable a disabled add-on, activate "Enable" from the actions menu.
After enabling, disabling, or removing add-ons, NVDA will prompt to restart when closing the add-on store.
Note that in this dialog ``escape`` works the same as the close button.
Any changes you had made in the dialog have already happened, but they don't take effect until NVDA restarts.

+++ Updating add-ons +++[UpdatingAddons]
When there is an update to an add-on you have installed, it will be listed in the "Updatable add-ons" tab.
Press ``control+tab`` to get to this tab from anywhere in the add-on store.
The status of the add-on will be listed as "Update available".
The table will list the currently installed version and the available version.
Press ``enter`` on the add-on to open the actions list; choose "Update"
Qchristensen marked this conversation as resolved.
Show resolved Hide resolved

++ Community ++[Community]

NVDA has a vibrant user community.
Expand Down