Standardized settings in user guide, + some wording corrections #16490
Conversation
|
@Adriani90 I am hesitant to review this, though I'm sure I'll have comments. You have conflicts with master, because you submitted this right before #16492, which removes/renames-and-changes the t2t files. |
|
Unfortunately you'll need to redraft this due to the timing of #16419 and #16492 |
|
Yeah It seems I chose the best timing to submit this. :)) |
Adriani90
force-pushed
the
Userguide-standards
branch
from
85b092f
to
1b61b22
Compare
user_docs/en/userGuide.md
Outdated
| NVDA can be configured so that the numpad Insert, Extended Insert and/or Caps Lock key can be used as the NVDA modifier key. | ||
| By default, both the numpad Insert and Extended Insert keys are set as NVDA modifier keys. |
There was a problem hiding this comment.
I agree with Sean re undoing these changes, but I'm also curious on the motivation to reinstate the use of "Extended insert" here? This was removed primarily because no-one had been able to find any documented evidence of this phrase (or any phrase) from Microsoft or anywhere else to distinguish the two insert keys.
user_docs/en/userGuide.md
Outdated
| |off |NVDA will not speak anything, however it will silently react to commands.| | ||
| |beeps |NVDA will replace normal speech with short beeps.| | ||
| |talk |NVDA will speak normally in reaction to screen changes, notifications, and actions such as moving the focus, or issuing commands.| | ||
| |on-demand |NVDA will only speak when you use commands with a reporting function (e.g. report the title of the window); but it will not speak in reaction to actions such as moving the focus or the cursor.| |
There was a problem hiding this comment.
can you please copy the same order as before? it matches the default order of the commands when switching
user_docs/en/userGuide.md
Outdated
| @@ -567,17 +567,22 @@ When the menu comes up, You can use the arrow keys to navigate the menu, and the | |||
|
|
|||
| ### Speech modes {#SpeechModes} | |||
|
|
|||
| | . {.hideHeaderRow} |.| | |||
| |---|---| | |||
| |Options |off, beeps, talk, on-demand| | |||
There was a problem hiding this comment.
can you please copy the same order as before?
user_docs/en/userGuide.md
Outdated
| This option is a checkbox that allows you to choose whether or not a dialog appears when you exit NVDA that asks what action you want to perform. | ||
| When checked, a dialog will appear when you attempt to exit NVDA asking whether you want to exit, restart, restart with add-ons disabled or install pending updates (if any). | ||
| When unchecked, NVDA will exit immediately. | ||
| This setting is a checkbox that allows you to choose whether or not a dialog appears when you exit NVDA that asks what action you want to perform. |
There was a problem hiding this comment.
I think it would be better to retain longer descriptions like this.
Thoughts @Qchristensen ?
There was a problem hiding this comment.
I am in favour of keeping the longer description here. I don't think it is overly verbose and may aid understanding for some users.
|
It seems like this PR is trying to achieve a large number of different things. |
There was a problem hiding this comment.
There are a lot of different changes through this and it is very hard to review all at once. Could I please ask to break it up into several PRs? I suggest:
One for changing all the "options" to "settings"
One for fixing the formatting of tables
One (or more) for various specific changes after that (eg the numpad insert one which is a distinct rewording of that paragraph - although in that case both Sean and I were not in favour of the change without further explanation, as we had just approved a PR to make that change (perhaps this was inadvertent if this branch was created before that issue was merged?)
user_docs/en/userGuide.md
Outdated
| NVDA can be configured so that the numpad Insert, Extended Insert and/or Caps Lock key can be used as the NVDA modifier key. | ||
| By default, both the numpad Insert and Extended Insert keys are set as NVDA modifier keys. |
There was a problem hiding this comment.
I agree with Sean re undoing these changes, but I'm also curious on the motivation to reinstate the use of "Extended insert" here? This was removed primarily because no-one had been able to find any documented evidence of this phrase (or any phrase) from Microsoft or anywhere else to distinguish the two insert keys.
user_docs/en/userGuide.md
Outdated
| This option is a checkbox that allows you to choose whether or not a dialog appears when you exit NVDA that asks what action you want to perform. | ||
| When checked, a dialog will appear when you attempt to exit NVDA asking whether you want to exit, restart, restart with add-ons disabled or install pending updates (if any). | ||
| When unchecked, NVDA will exit immediately. | ||
| This setting is a checkbox that allows you to choose whether or not a dialog appears when you exit NVDA that asks what action you want to perform. |
There was a problem hiding this comment.
I am in favour of keeping the longer description here. I don't think it is overly verbose and may aid understanding for some users.
However, long descriptions contain lot of duplicate information that we already explain in a focused way within the tables. @seanbudd
That older discussion actually refered only to the first table, where we just show up which options are available and which one is the default. |
Yes that seems to have conflicted, it is reverted now. I think we can solve your suggestions via single commits, it is in my view better administrated in this case. |
I think that was because of some conflicts which should be solved now. |
In this case, keep this PR for the tables and remove other changes from this PR to put it in separate PRs please. @Adriani90, I know that you have done a big job in this PR. |
However, changes made to the text which have been incorporated into the tables will be part of this PR though. We cannot merge the tables only and let double statements and descriptions in the same sections, this will definitely create confusions. The only part that I can logically separate is the lines with the word "option" becomming "setting" in appropriate place. This will be a small part of this PR. I strongly suggest you take the html file generated by this pr, look at the line numbers and compared side to side what changed in case you are not confortable with how github displays diffs.
Can you explain more exactly what you mean? When you compare the both html generated user guides you can exactly see what changed. All the settings part of the user guide has been converted into table structures, and the original text descriptions have been removed and incorporated into tables instead, in order to avoid duplications.
What do you mean by that? All changes I made in this PR are related to the user guide standard, which is directly related to the tables, even changing the "option" to "setting" is required to be in line with the table structure. It is not feasible to split this work into lots of PRs for each section of the user guide.
This is a change in user guide standard compared to what we had before, I think translators will have to go through this work unfortunately, in case NV Access wants these standards to be pushed.
i agree. |
|
Re the longer description comment - Here - I was thinking of the names of things like "Restart with add-ons disabled", or install pending updates (I haven't got any to check the exact wording) which actually aren't explicitly mentioned anywhere else - I was thinking if a user was looking at the exit screen options and found that and wasn't sure what it does, it is good to be able to search the user guide for the wording they are presented with |
|
It is useful to have a plain english description as well as a table. There's no need to remove this content when creating tables. |
|
Might be true for sighted people, but having to read lots of double descriptions is confusing when you use a screen reader. I can redesign that but I am quite sure we will come back to this conclusion. Did you look at the html file and compared it with what we have in master?Von meinem iPhone gesendetAm 22.05.2024 um 07:25 schrieb Sean Budd ***@***.***>:
It is useful to have a plain english description as well as a table. There's no need to remove this content when creating tables.
Tables should be moved to the bottom of sections. Having a general description first and then structured data is more common in reference materials. For example:
https://learn.microsoft.com/en-us/windows/win32/api/audiopolicy/nn-audiopolicy-iaudiosessionevents
https://git-scm.com/docs/git-revert
https://linux.die.net/man/8/apt-get
—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>
|
This PR is very large. And I will not be able to review it carefully. If changes unrelated to structure had been isolated in another PR, I could have reviewed them carefully. Just my opinion though. |
Looking at the HTML file generated through this PR, the section for exit options looks as follows: So all the information that was in the long plain text description before is still here, it is just described in the behavior table. So in my view it doesn't make sense to keep the same description also above the tables, because then the user guide becomes really blown up and quite unreadable. @CyrilleB79 everything in this PR is related to the tables and the user guide standards. |
In this case, you may drop "+ some wording corrections" from the title of this issue. What was it referring to? In any case, there is at least the "option" vs "parameter" changes which are not linked to the tables. Why this specific rewording? |
|
Ofcourse they are related to the tables. Tables describe the options for specific settings, so this difference needs to be consistent throughout the user guide. To be honnest I am a bit shaking my head when reading about what is questioned here. You should really check the html file.Von meinem iPhone gesendetAm 22.05.2024 um 08:48 schrieb Cyrille Bougot ***@***.***>:
@CyrilleB79 everything in this PR is related to the tables and the user guide standards.
In this case, you may drop "+ some wording corrections" from the title of this issue. What was it referring to?
In any case, there is at least the "option" vs "parameter" changes which are not linked to the tables. Why this specific rewording?
—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>
|
@Adriani90 - we discussed this internally and Sascha and Mick don't see this issue you describe. This structure is extremely common in reference materials, and they don't understand the confusion you describe. Surely table content can be skipped over when the reader is not interested in it? |
…pt old descriptions above tables, the term setting and option is still used in wrong way in several sections.
I don't have anything against tables, I was only refering to the fact that the long descriptions of settings behavior have been moved into tables, so no need to display them again above tables. What you linked above is the style of Microsoft to display reference material, which is article style. But the user guide as it is now does not contain that much description in the settings areas apart from what we describe in tables. I moved now all tables to the bottom of each section and kept the old descriptions above. If you don't like this, I can revert the last commit. In my view the user guide as it is generated now per last commit is not really well readable, contains many unclear settings and contains lot of duplicate descriptions which makes it difficult to read for people who need easy english language. I wished you at NV Access would have spent some time to provide some constructive arguments, but it is how it is. Now you can decide the next steps, I will stop the work on the user guide at this point because for me it is too much work to adjust everything in new pull requests. I understand this for a coding perspective, but not really for the user guide. Now we have sections, where the setting is called option, and the option contains options. Confusing... but yeah. |
|
I fully agree with @Adriani90 that duplicating the content makes things less easy to read. Except for the revert of last commit, I'd say that next changes should be done on one or two paragraphs illustrating the wanted change. Once an agreement has been found on the structure and content of these paragraphs, the work can be duplicated to the rest of the User Guide. |
|
@CyrilleB79 - to be clear, what was proposed in #15902 (comment) was a PR that just added tables to the bottom of each section. My previous comment requested opening a discussion or issue first for any other scenario. I would highly encourage a separate issue or discussion before proposing wider changes than this. |
|
But a table contains already accessible plain text, there is no need for duplicates in this regard.
Sean the changes to the user guide have to be this huge if you guys propose such new standards. Putting e.g. every table in a single PR is not efficient at all. And me at least speaking for myself out of my voluntary perspective, I will not do that work. I don‘t think reviewing such complex changes to the user guide are more challenging than reviewing e.g. 1000+ lines of code. And we have several PRs with that amount of code.
At least with the user guide you can put the html files side to side and compare the real changes much easier. I am not really following the argument you bring on the table.
It is certain that if we merge the tables only as per current stage of this PR, the user guide will become a chaos and less accessible.
|
|
@seanbudd, I have the feeling that NV Access expectations are not clear. Let's take an example to be extra clear: the paragraph "Save configuration on exit" In the current version of this PR,this paragraph consists in 3 parts in this order:
Before this PR, the description of an option was done as follows:
Ragarding the presence of each part and their order, is NV Access expecting to do:
Regarding the plain text part, is NV Access expecting:
The first commit of this PR (1b61b22) implements choice 2 + choice B.. Then NV Access has asked to restore the original plain text content, leading to choice 2 + choice A. But as explained by @Adriani90 and myself, choice 2 + choice A is probably not desirable due to a lot of duplication leading to readability and maintainability issues. Thanks for future clarifications! |
|
Choice 2 was what I did first, I bassically created the behavior tables and incorporated all the old descriptions there. That version of this PR would have been easily maintainable. But that was not what NV Access seemed to expect, so now we have all the descriptions double, both in the behavior tables and above the tables.Von meinem iPhone gesendetAm 24.05.2024 um 10:21 schrieb Cyrille Bougot ***@***.***>:
@seanbudd, I have the feeling that NV Access expectations are not clear.
Let's take an example to be extra clear: the paragraph "Save configuration on exit"
In the current version of this PR,this paragraph consists in 3 parts in this order:
A plain text description of the option
This option is a checkbox that, when checked, tells NVDA to automatically save the current configuration when you exit NVDA.
A table listing the possible choices of the option and indicating the default one
| . {.hideHeaderRow} |.|
|---|---|
|Options |enabled, disabled|
|Default |enabled|
A table describing the effect (behaviour) of each possible choice
| Option |Behaviour|
|---|---|
|enabled |NVDA will automatically save the current configuration when you exit.|
|disabled |NVDA will exit directly without saving the configuration. The changes to the settings of
Before this PR, the description of an option was done as follows:
Either only plain text (part 1)
Or, for newer ones and as per the new guidelines, choice listing table (part 2) followed by plain text (part 1)
Is NV Access expecting to do:
Choice 1: only move the option listing table (or create it) below the plain text description, i.e. part 1 followed by part 2.
Choice 2: move the option listing table (or create it) below the plain text description and below this table, create a new table explaining the behaviour of each choice, i.e. part 1 followed by part 2 and then part 3.
Choice 3: another choice (please explain)
As explained by @Adriani90 and myself, choice 2 is probably not desirable due to readability and maintainability issues.
Thanks for future clarifications!
—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>
|
|
I have edited my previous comment (#16490 (comment)). Choice 2 is what has been done initially as well as the current state of this PR. But it was initially choice 2 + choice B. Now it is choice 2 + choice A, which is not desirable. |
|
There have been several requests in the PR for NV Access to clarify their position. NV Access's stance is to retain both the text and table formats, while minimising redundancy. The text should come first, offering a concise summary and providing necessary context and clarification without detailing specific behaviours. The table should follow, containing all the detailed information, including the behaviour of each choice. The question is, how do we get to there from where we are now? We also need to consider if right here is a place that we want to be. And if not, how do we avoid finding ourselves in this situation again? To move forward, we have to recognise that any effort to change the user guide is magnified 50x by the need for translations. Therefore, we need to be considerate of our translators and be sure that the cost of any changes is justified by the nature of the changes. We also need to consider how they work, for example translators must translate the entire diff each commit. We have a few options:
Due to the magnitude of the change I suggest we need feedback from our translators on what method works best for them. Additionally, we must consider if our current starting point is optimal. Large diffs with numerous changes can overwhelm translators. More worryingly there appear to be changes to the content as well. Consider the changes in "Move system caret when routing review cursor" which changes the listed options. Refactoring must be done methodically and carefully to avoid error slipping in, particularly with large refactors. Keeping PRs separate for different goals can help with this. I suggest the way forward is to get confirmation from the translators on their preferred approach, and for the developers to make a call on whether the current PR can be salvaged. I hate to be so blunt, but if github is struggling to show rendered diffs, this might be too large to work with. Adriani should maintain a backup to verify the intended changes are all in the final product. Looking forward to your insights and suggestions. |
|
@gerald-hartig thanks for your contribution here, following are my thoughts.
That was the initial state of this PR and still NV Access was not keen with it. Redundant text was moved into tables, and the rest of the description, if any, was still outside of the tables. For translators this would have been basically a copy and paste task, + some rewordings for more clarity and coresponding additions for opsions behaviors that are not documented yet in the master.
How does this relate to the previous point of minimizing redundancy? In my view the tables should contain only the behavior of each option, and the available options out there. Outside of the tables is anything else related to description of specific use cases for a specific setting or option, keystroke documentation etc.
That's not possible without redundancy. Our settings subsections are very short as such. Apart from the behavior description, we have a clear title for a setting which in many cases does not need further introductory description, and in some cases we have recommendations and descriptions of use cases. But if you want to understand the setting from a readers point of view, in some cases you have to first understand the behavior of the setting's options, and then read the recommendations, descriptions of use cases, warnings etc. That's why initially the tables were not always at the bottom of each section.
The current state of this PR as of now is definitely not the place we want to be. I think it would have been better to have a more in depth look at the initial state of this PR and add introductory text if really needed, and only for the sections where it makes sense, but at a later stage.
This option is not viable in my view, theredundant text was moved into tables in the initial state. Translators would have seen that as well while translating, because the coresponding lines would have been preceded by a dash and the lines in the table would have been shown with a plus sign.
That was my initial state, while the word "option" was changed to "settings" in appropriate places to make the difference clear throughout the user guide.
I am a translator myself, and I noticed that almost all countries have more than one translator. So the work would be splitted to more than one person.
The current description of that setting in the current master is quite difficult to read, I just splited the parts accordingly and put them into the behavior table which makes it much more easy to follow.
Making the user guide compliant with the user guide standards definitely will need rewording of some text because it needs to fit into behavior tables. From my voluntary perspective this would be too much work to split it into multiple PRs, but I am happy to keep this work documented and someone else can take it into separate pull requests.
I agree with this approach as long as there is full clarity on how the user guide should really look like in the end. To me it is still not clear enough at this stage. Maybe it would make sense that you at NV Access change some settings sections in a separate pull request so that we can see a clear practical example of what you expect. Then I could easily adapt this work to your expectactions for the rest of the settings sections. |
…6667) Summary of the issue: As discussed in #16490 and #15902 (comment) that feature descriptions should come before settings tables for features in the user guide. This is because a basic description is more common than detailed tables in reference manuals Description of user facing changes Fixes up order for feature descriptions in the user guide standards
Summary of the issue: As discussed in #16490 and #15902 (comment) that feature descriptions should come before settings tables for features in the user guide. This is because a basic description is more common than detailed tables in reference manuals Description of user facing changes Fixes up order for feature descriptions in the user guide standards
Link to issue number:
None
Summary of the issue:
In #15902 it became obvious that we need structured data in the user guide, so I prepared a PR.
Description of user facing changes
Settings and their options along with the effect on NVDA behavior are now much clearer documented.
Description of development approach
Adjusted the user guide in line with user standards, among others introduced in #15950.
Testing strategy:
Tested that tables are shown correctly in browser when opening the user guide.
Known issues with pull request:
Not sure if there is something messed up visually though, someone needs to check.
Code Review Checklist: