Proposal: a series of posts/articles on NVDA internals


Hi all,

After looking at recent messages on this forum, I thought about proposing the following:

Most of you may know me as a code contributor to NVDA screen reader and author of several add-ons. But I don’t think many of you may know me as the producer of several NVDA tutorials, notably Welcome To NVDA series (2013, 2015, 2018); and no, I don’t think there will be a fourth edition of that tutorial series as NV Access sells Basic Training module and several community members are producing excellent tutorials. What I propose is something a bit different, something that was only seen on NVDA add-ons and development lists:

As I reflect on NVDA development and user interaction for the last ten years, I realize that the biggest missing piece of information is a document or two that explains NVDA internals to users so folks can appreciate how a screen reader works. Although we do have documents explaining NVDA internals from developers’ perspective, I understand that there is no such document from users’ perspective. Although I understand that folks can glimpse the screen reader from afar, I realize that some folks would like to know more about the actual internals of NvDA features, and in some cases, bugs.

The recent discussion on configuration profiles and backing up settings made it clear that the users community may benefit from a screen reader internals document. While anyone can see NVDA source code and figure out how things work, without context, folks won’t know how a feature fits into the overall picture.

Therefore I propose a series of articles/posts on NVDA feature internals at the user level. That is, upon request from the community, a series of posts will be written that explains how a feature works internally. The overall purpose of this proposal is to let users see what’s going on behind the scenes and appreciate the complexities (and not so complex parts) of screen reading technology. Obviously this will involve explaining NVDA source code, but just copying and pasting source code would not help many. Therefore I propose posts that use techniques such as storytelling to explain how NVDA features work behind the scenes. And no, I intend these series to not replace In-Process blog posts on feature overviews – I would imagine the posts I’m proposing are a bit geekier than blog posts. As for authorship, I hope I won’t be the only one writing these – I hope these exercises would serve as a way for would-be developers on this list to learn about talking to multiple audiences and discuss technical material.

To get started, tell us what is one feature in NVDA that you are really curious about how it works behind the scenes. To avoid this becoming a really lengthy thread that can go elsewhere, please do your best to write to me directly, or if you want, tell folks about the feature and talk to me directly with details. I will accept suggestions until January 23, 2022, at which point I will choose the top three requests and post internals about them, hopefully in February and March.

For a sample of the kind of writing I will post, take a look at add-on internals document for Control Usage Assistant:

cuaaddoninternals · nvdaaddons/DevGuide Wiki (


A bit geeky, but I hope you learn something useful. I expect the proposed articles/posts won’t be that geeky since the upcoming documents will be written with users in mind.

Also, if you are interested in learning more about the writing process for articles/posts like these, do ask me directly so I can look into leading a workshop on documentation writing, or perhaps something for a future NVDACon.




Join to automatically receive all group messages.