Restore numbered sections in the User Guide

[CyrilleB79]

Steps to reproduce:

Since the merge of #15945, the headings in the User Guide are not numbered anymore. It was a known fact when developing #15945. I guess it was not specifically intended, even if this change is described in "Description of user facing changes" rather than in "Known issues with pull request:" section of #15945.

Actual behavior:

No more heading numbers.

Expected behavior:

If possible, restore heading numbers.
They are very useful when indicating a paragraph to read to someone else.

NVDA logs, crash dumps and other attachments:

N/A

System configuration

NVDA installed/portable/running from source:

installed

NVDA version:

2024beta4

Windows version:

N/A

Name and version of other software in use when reproducing the issue:

N/A

Other information about your system:

N/A

Other questions

Does the issue still occur after restarting your computer?

N/A

Have you tried any other versions of NVDA? If so, please report their behaviors.

Number present in 2023.3

If NVDA add-ons are disabled, is your problem still occurring?

Yes

Does the issue still occur after you run the COM Registration Fixing Tool in NVDA's tools menu?

N/A

[Qchristensen]

Can you elaborate more on the usefulness of the numbers please @CyrilleB79? I must admit, my first reaction to the idea was also "but they're useful!" - but the more I think about it, I'm not convinced that is true, but would be interested in hearing from others on it.

[ruifontes]

Numbers are important to indicate a section to an user...
You can say, please read chapter 5...

[Qchristensen]

In that case though, wouldn't it be easier to ask them to "Please read the chapter on navigating with NVDA"? Giving the name avoids any possible confusion if the number has been changed or is incorrect.

One benefit of numbering is in a case where you have a physical book (or a mouse user navigating with the scroll bar in an electronic text) and can quickly jump to, for instance "about the middle of the book". That doesn't apply to the majority of NVDA user, but even using that method you still need to find the exact page / topic.

In almost all cases, would it not be easier to do a text search for, say "Object navigation", and jump to either the Table of Contents link to a topic on that, or to that phrase in the text itself? In the case of the ToC link, you then HAVE a link you can pass to someone you are helping to save them looking it up themselves.

Searching for any other written guidance on this online, I couldn't find anything explicitly saying you should / should not number topics in a user guide. There are plenty of instructions for creating lists (especially in Word), which explain the difference between bulleted and numbered lists is primarily that you should use numbering when the order is important. I also found guidance for writing user guides which suggested that you should assume the user has read absolutely nothing aside from the specific topic you are now writing.

While the NVDA user guide is intended to be laid out logically, if you want to find out how to connect your Braille display (in what is currently section 16 of 18, towards the end of the file) for instance, there is no need to be familiar with the previous 15 sections of the document.

Looking for some user guides online to see what other's do:

• the iPhone has a user guide which is in sections with a ToC, but not numbered.
• This Samsung fridge gives page numbers, but no numbering (and it's in French, I don't think that's important here).
• Many others like Firefox, Adobe Acrobat and so on, don't even have a (readily available) user guide, but rather trying to get help from their menu takes you to their knowledge base or FAQ / search for a topic.

Numbering sections and topics is important in the training modules, because the intention is that users will work through them in order, and in that case, the contents of section 16 of Basic Training will rely on knowledge covered in the previous 15 sections. In the case of the user guide, users generally open it when they need help with a specific problem, and in that case, will be looking for information about that issue, rather than working through in a sequential order.

If there is a good argument for keeping numbering in the user guide we haven't thought of, please do let us know.

[CyrilleB79]

@Qchristensen, in "Expected behavior:", I have written:

If possible, restore heading numbers.
They are very useful when indicating a paragraph to read to someone else.

I have decided to open the current issue when I have answered to this thread. One person asked where he could find information on the new speech on-demand feature. I have had to answer with the title of the paragraph ("Speech modes"), but a paragraph number would be more straight forward.

More generally, it was a common usage to give the paragraph number: it is quicker for the person providing the information to give it than to do a copy/paste. Also, for the person who reads the answer, it is easier to mentally isolate a number from the rest of the sentence than if the text of the heading is provided.

Question:
Was this removal of section numbers intentional? Or has it been done just because it was easier (technnically) to remove them; e.g. less work to do for the conversion.

[CyrilleB79]

Looking at other digital User Guides, it seem to me that number are generally not used, especially in more modern documents. I am not against following this practice if we find it suitable for NVDA; people will adapt when referring to the User Guide. I just wanted to have this discussion because I thought that this removal was an oversight.

On one side, keeping the numbers are interesting to reference quickly a chapter, as written before. On the other side, removing them allows to get more quickly the useful information when reading the table of content line by line or navigating the User Guide heading by heading (H key).

@Qchristensen wrote:

In that case though, wouldn't it be easier to ask them to "Please read the chapter on navigating with NVDA"? Giving the name avoids any possible confusion if the number has been changed or is incorrect.

Note that the name too may be changed or reported incorrectly or approximatively. Moreover, for a specific version of the UG, the number identifies uniquely a paragraph whereas the name may appear various times (e.g. "The Elements List" appears three times).

So I would say that both the name and the number may be useful and that it depends on the situation.

In almost all cases, would it not be easier to do a text search for, say "Object navigation", and jump to either the Table of Contents link to a topic on that, or to that phrase in the text itself? In the case of the ToC link, you then HAVE a link you can pass to someone you are helping to save them looking it up themselves.

Passing the link with the name or the number as visible text is best practice for a careful document of course. The person writing the advice should take care to use the version of the User Guide on the web and not the local one, so that the link be accessible by the person reading it.

Let's wait for the reaction of other people so that we decide if we close this issue or not. We may also release 2024.1 without numbering and see if people get accostumed to this new presentation or not. If not, we may still imagine to restore the links in 2024.2.

[paulber19]

Was there a strong request for the title numbering to be removed? If not and without a valid explanation, it looks like a regression. Agree with Cyrille's arguments, I am for maintaining this numbering. Le 18/01/2024 10:03, Cyrille Bougot a écrit :

…

Looking at other digital User Guides, it seem to me that number are generally not used, especially in more modern documents. I am not against following this practice if we find it suitable for NVDA; people will adapt when referring to the User Guide. I just wanted to have this discussion because I thought that this removal was an oversight. On one side, keeping the numbers are interesting to reference quickly a chapter, as written before. On the other side, removing them allows to get more quickly the useful information when reading the table of content line by line or navigating the User Guide heading by heading (H key). @Qchristensen <https://github.com/Qchristensen> wrote: In that case though, wouldn't it be easier to ask them to "Please read the chapter on navigating with NVDA"? Giving the name avoids any possible confusion if the number has been changed or is incorrect. Note that the name too may be changed or reported incorrectly or approximatively. Moreover, for a specific version of the UG, the number identifies uniquely a paragraph whereas the name may appear various times (e.g. "The Elements List" appears three times). So I would say that both the name and the number may be useful and that it depends on the situation. In almost all cases, would it not be easier to do a text search for, say "Object navigation", and jump to either the Table of Contents link to a topic on that, or to that phrase in the text itself? In the case of the ToC link, you then HAVE a link you can pass to someone you are helping to save them looking it up themselves. Passing the link with the name or the number as visible text is best practice for a careful document of course. The person writing the advice should take care to use the version of the User Guide on the web and not the local one, so that the link be accessible by the person reading it. Let's wait for the reaction of other people so that we decide if we close this issue or not. We may also release 2024.1 without numbering and see if people get accostumed to this new presentation or not. If not, we may still imagine to restore the links in 2024.2. — Reply to this email directly, view it on GitHub <#16059 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADZLFFFT5KL2ZS2FOE75PI3YPDQOHAVCNFSM6AAAAABB7JCHN2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOJYGA3DMMBYGQ>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[XLTechie]

Numbers have one main use from my point of view.

They allow you to reference a section, without remembering its exact name in the target language, sufficient enough for a text search.

"Oh, that's in 12.5 of the user guide".

The other aspect of that, I think, is to enable someone reading in a language
other than the language the help recipient is using, to give a more common
language of reference.

It's easier to point someone who doesn't speak your language well to 5.2, than
it is to a chapter/section title that you may not translate exactly enough for
them to do a text search.

E.g. "5.2. Navigating with the System Focus":

In Arabic, this is apparently something like: "5.2. التنقل باستخدام تركيز النظام".

When back-translated through Google translate, I get: "5.2. Navigate using system focus".

The only part of that which survives across the machine translation from English to Arabic to English, is the "5.2", and the "system focus". The final English phrase is sufficient to make the point, if that's all our hypothetical help giver wanted to do, but the phrase will not succeed in a text search to reach that section any more. However the 5.2 still works just fine.

[ramoncorominas]

One possible argument against section numbers is that it could make more difficult if in the future you want to reorder or reorganize the guide, since the old number references will become outdated and possibly generate confusion; for example if someone reads an old blog post that uses the old numbering.

[seanbudd]

This change was intentional, not an unexpected regression, as specified in the changes for users, not issues with the PR.

Please note that markdown does not support automatic header numbering. This means that we must manually maintain numbering if we are to restore it. We can generate a base numbering when converting t2t to markdown, but when markdown becomes the source of truth, translators and documentation writers must manually update and ensure these are kept up to date.
We figure this burden is not worthwhile and likely to not be kept accurate with manual maintenance. Translators can always add their own numbering even if english maintainers refuse to. We'd need a strong argument to manually maintain this numbering.

The extra processing we need to do to restore them is minimal. when auto-generating the numbers in t2t to markdown conversion, they need to be reversed for arabic and Persian.
They also need stripped from the key commands doc when generating that.

[ramoncorominas]

@seanbudd I don't know if this is feasible in the context of NVDA User Guide, but maybe you could create automatic numbering using CSS counters and the pseudo-elements ::before and ::after.

[seanbudd]

@ramoncorominas This looks feasible, thanks

https://www.freecodecamp.org/news/numbering-with-css-counters/

[CyrilleB79]

Note that after thinking to it a bit more, I am unsure of the best solution. Keeping or removing numbering have both pros and cons:

• Keeping the numbering allows to quickly give a paragraph reference when providing help, e.g. on the mailing lists. It's commonly used and helps teaching people to look at the User Guide, rather than just providing them the answer by copy/pasting the target paragraph.
• Removing the numbering allows to avoid being disturbed by unuseful information when reading line by line the table of content or when navigating heading by heading in the document; it allows to focus on the useful information which is the heading without the number.

Many people have expressed their interest on the first point, but there has been no reaction on the second one. Does it mean that it seems not or less important to you?

[seanbudd]

With CSS we also have the option of just numbering the table of contents, and not the headers, or vice versa