Re: NVDA Settings Documentation


Quentin Christensen
 

Off the top of my head, this doesn't work in Word, because as you down arrow to move by line, the caret DOES move down a line, and so NVDA reads the next line (that behaviour is the same in focus or browse mode).  Using the Move to next line in review command (numpad 9 or NVDA+down arrow) also moves to the next actual line.


On Thu, Oct 22, 2020 at 8:41 AM Dave Grossoehme <dave@...> wrote:
Good |Day:  This brings a question to mind on this setting. Would that
work for a line in Word, if wrap is turned on?  Which a line of text
that continues to wrap.

Dave


On 10/19/2020 2:14 AM, Gene 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.
>
> Gene
> -----Original Message----- From: Quentin Christensen
> Sent: Monday, October 19, 2020 4:01 AM
> To: nvda@nvda.groups.io
> 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 bed).
>
>
> 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!
> http://stream.wrighthere.net:8000/stream.mp3
>
> 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
> To: nvda@nvda.groups.io
> Sent: Sunday, October 18, 2020 1:45 PM
> Subject: Re: [nvda] NVDA Settings Documentation
>
>
> Hi,
>
> Agreed (that’s one of the reasons why I comment a lot in my add-on
> source code).
>
> 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.
>
> Cheers,
>
> Joseph
>
>
>
>
>
>
>
>
>
> From: nvda@nvda.groups.io <nvda@nvda.groups.io> On Behalf Of Brian Vogel
> Sent: Sunday, October 18, 2020 11:56 AM
> To: nvda@nvda.groups.io
> Subject: Re: [nvda] NVDA Settings Documentation
>
>
>
>
>
> Joseph,
>
>           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.







--
Quentin Christensen
Training and Support Manager

Join nvda@nvda.groups.io to automatically receive all group messages.