Re: NVDA Settings Documentation

Quentin Christensen

I think having the maximum number of characters per line setting described where it is in the browse mode settings section is fine  - where the previous section 6 covers Browse mode in general, the settings section covers how to change the behaviour of different aspects.  So for that setting particularly, currently the user guide simply offers:

"Maximum Number of Characters on One Line
This field sets the maximum length of a line in browse mode (in characters)."

I guess when working out where best to add information, what would you suggest needs adding?  That seems to describe the feature to me, but maybe I am too familiar with it to see what is missing?

If anything more was needed on that, I'd be inclined to consider covering it in more depth in the "Basic Training for NVDA" module moreso than the user guide.

On Mon, Oct 19, 2020 at 8:14 PM Gene <gsasner@...> wrote:
I haven't looked at the user guide a lot.  However, I found yesterday,
regarding the line length documentation this:
12.1.14. Browse Mode (NVDA+control+b)
The Browse Mode category in the NVDA Settings dialog is used to configure
NVDA's behaviour when you read and navigate complex documents such as web
pages. This category contains the following options:
Maximum Number of Characters on One Line
This field sets the maximum length of a line in browse mode (in characters).

That's true but how many people would understand where it might be useful?
I found the same feature useful in JAWS years ago becaused when I moved from
line to line manually, the lines as displayed were too long to find
something conveniently.  I wanted lines shorter so I could skim by line much
faster and more efficiently.

There are two things that come to mind:
When browse mode is discussed earlier, should the section that shows the
settings with explanation be referenced as a further information or see
also, or for settings, see or something of the sort?  Also, is this section
and some other parts of the user guide intended for those who already have
an idea of how such settings might be used in general or for a more advanced
user who may either understand the information or play around and see what
the effect is of settings information that isn't clear.

Manuals, in my experience are usually concise and I think that is one reason
tutorials are so much more popular.   But the degree of concision may be
opened to useful discussion.

-----Original Message-----
From: Quentin Christensen
Sent: Monday, October 19, 2020 4:01 AM
Subject: Re: [nvda] NVDA Settings Documentation

Hi everyone,

Lots of good points here.  So firstly, from a very simplistic view - if
there are any settings which experienced people such as yourselves can't get
an explanation of from the User Guide, then that's definitely something we
should address.  Please either let me know (or file a GitHub issue) as you
find examples.

Re the user guide being too thick and heavy for new users to get start
with - that's largely because that's not who it is really aimed at.  For a
lot of users, the Basic Training for NVDA would be the best place to start.
There is potentially a gap for a short "quick start" guide, and I'd be happy
to explore that further with anyone who has ideas on the subject.

Joseph, re some sort of training for new contributors - that too is a great
idea, and I'd be happy to work further with you on it.

I've made a note to follow all of this up (since it's into the evening here
and I'm trying to figure out book week costumes while getting the kids to

On Mon, Oct 19, 2020 at 10:44 AM Robert Doc Wright godfearer
<godfearer@...> wrote:

Where I need direction on what I need to study in order to be a tech writer
for NVDA. I believe that once I understand something I can teach it to
anyone. My stumbling block is that I have had some programming classes but
that was twenty years ago. I taught myself basic web design from a book.
What do I need to know to be of help where the users guide is concerned?
Jesus says, follow me and I'll help you through the rough spots.
the world says, hey come with me. My way is broad and easy. So what if you
get crap on your shoes. You can always wash it off, can't you!

Family times where there is fun for every ear!

Or ask your A device to play Family times on tuneIn
You can also find us on your mobile device install OoTunes and search for
Family times
----- Original Message -----
From: Joseph Lee
Sent: Sunday, October 18, 2020 1:45 PM
Subject: Re: [nvda] NVDA Settings Documentation


Agreed (that’s one of the reasons why I comment a lot in my add-on source

One holiday wish I have (possibly a long-term wish) is to help folks get
started on revamping the NVDA community documentation. At least this can
include add-on user guides, but I foresee a day where the screen reader user
guide would not escape this rewrite in hopes of making it more relevant for
users. I would go so far as ask NVDA code contributors to add extensive
documentation in source code itself – it is now possible to do it easily
with help from a module called Sphinx, a source code based documentation
generator. There are major issues to consider, however:

Who is the target audience: thinking about this changes the game, as it will
dictate tone, style, word usage, and organization of the document and
supplemental materials.
Mindset of code contributors: are we just software developers or technical
authors? Some people would argue that developers should focus on programming
and testing, leaving the task of documenting what developers wrote to
technical authors, and this separation of concerns may foster better
communication amongst team members. On the other hand, by forcing developers
to become technical authors, they can make crucial decisions about the
user-visible aspects of a given product a bit early.
How can we show we accept diversity in terms of culture, language, skill
level, and other factors: although the community documentation was written
by NV Access people at first, it is increasingly written by people from
diverse backgrounds in terms of culture, language, skill level, and other
factors (although I did receive training on technical communication and
software development, I’m not a native English speaker). This is more so for
parts that are written by people who may have different interpretation about
a UI message or concepts, more so if the author’s native language is not
English (the reverse is true for translators as they need to grasp concepts
written in English in their native languages).

My responses to the above questions are:

Who is the target audience: it varies. For NVDA user guide, it is users with
differing skill levels. For add-on guides, they target end users. For this
reason, whenever I edit the NVDA user guide or add-on guides, I think about
what users expect and NVDA’s response. This changes if we’re dealing with a
document meant for developers (such as add-on internals and such).
Mindset of code contributors: I believe that, as much as programming skills
is important, willingness to communicate with audiences (users, other
contributors, industry experts, etc.) is also important. One way to practice
both is thinking and writing to and about users, therefore I tend to fall
into a bit of the latter category from above: programming is, in one way or
another, writing. Python is just one of the more specialized languages used
to communicate with another entity (the machine), and if one can teach a
computer to do something (along with fixing mistakes), it would be possible
to train developers to respect users more by writing good documentation (of
course someone may need to look at the documentation for style and such). My
philosophy partly stems from my experiences as a former computer science
major at a college I attended (different from the one I’m about to graduate
from): my first computer science professor stressed the importance of source
code comments and documentation, and I still practice this lesson today,
which fuels my overall frustration with the current state of NVDA user guide
and source code documentation in general. I think one exercise code
contributors can do before submitting anything to GitHub (specifically,
pull; requests) is writing an early user facing documentation, because doing
so helps you improve your writing skills and think carefully about the
impact of your changes when users meet them (I sometimes find myself
struggling for minutes to hours over UI messages and documentation for this
reason; I know what my code will do, but I hit a roadblock when explaining
what I’ve done to would-be users before actually writing code).
How can we show we are a group of people coming from diverse backgrounds: I
think this goal was somewhat achieved when we look at recent NVDA work –
many new features and bug fixes included in NVDA 2020.3 were written by
someone other than an NV Access staff member, from people living in
different countries and speaking many languages. But I know that we can
improve on that somehow.

Another wish I have, mostly for Quentin: can we develop some sort of a
training program for would-be contributors wishing to improve the overall
NVDA community documentation, including the user guide? It may include
basics on technical writing, tone and style, audience analysis, exercises
where coding and documentation should be done together, and documentation
production in a variety of formats (including online media). I think this
may help us dive deeper into user guide issues being brought up, including
the guide being “too thick” for newbies (in terms of understanding, lack of
solid examples, and friendliness), especially for preferences chapter.



From: <> On Behalf Of Brian Vogel
Sent: Sunday, October 18, 2020 11:56 AM
Subject: Re: [nvda] NVDA Settings Documentation


           While I applaud your efforts, and tutorials are invaluable, I
wasn't even going that far.  I'm talking basic documentation, where each
item in a panel/pane/settings group in a given pane are briefly documented.
There are myriad NVDA settings that, if their actual function is not
directly obvious, which is the case, for example, with most checkboxes, then
they're a black hole.

            Even I will admit that for all software it is a limited number
of end users who refer to this sort of thing.  That being said, some do, and
it serves as a very important basis for new developers to develop depth of
knowledge of "what's in there and what it's for."

             I was just commenting to someone for whom I've done custom VBA
scripting for Outlook that I am eternally grateful to myself for having
developed the habit of rigorously commenting my code, at a bare minimum, as
even I would have no idea what some of what I've written actually does when
looking at it much later.  Complex stuff doesn't remain in "off the top of
my head" mode (for most "mes") as time moves on.  That's one of the reasons
that basic documentation is so important.

Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041

It’s hard waking up and realizing it’s not always black and white.

     ~ Kelley Boorn


Quentin Christensen
Training and Support Manager

User group:
Twitter: @NVAccess

Quentin Christensen
Training and Support Manager

Join to automatically receive all group messages.