Re: Request for comments: an outline of a complete course on NVDA internals and code contributions


 

Hi,
Bringing log viewer and Python Console to earlier units: that won't happen until people get a gentle intro to NVDA's architecture and source code layout and grasp Python somewhat. I will integrate both facilities throughout the course (especially during debugging lessons), but there will be a later lesson that'll unlock some advanced features such as tab completions.
Also, one of the reasons why I did not mention these facilities earlier is due to my personal philosophy: the end goal isn't just about NVDA code contributions; rather, it is training people to become proficient at problem solving and critical thinking, as code contribution won't be complete without these. One thing I will stress during this course is that code isn't everything - there are other things to learn and practice as people become familiar with intricacies of code contributions and basics of collaborative software engineering. For this reason, majority of exercises will ask people to write sentences, not code Python modules in order to test if people are really thinking things through. Of course, some difficult exercises will ask people to use Python Console and write code that is really a "short essay" to practice what they've learned, at the same time, I will be asking people to tell me some stories about how they understand what NVDA is doing. In other words, before end of the course, I want prospective code contributors to learn what it is like to be a NVDA developer for a while so they can be better prepared than doing a bunch of coding exercises and remembering recipes without a chance to deepen their understanding.
Cheers,
Joseph

-----Original Message-----
From: nvda-addons@nvda-addons.groups.io [mailto:nvda-addons@nvda-addons.groups.io] On Behalf Of Robert Hänggi
Sent: Sunday, August 20, 2017 12:48 AM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] Request for comments: an outline of a complete course on NVDA internals and code contributions

On 20/08/2017, Joseph Lee <@joslee> wrote:
Hi,

The course is free.
That's generous.
After all, the goal is to bring additional contributors to NVDA and they are sacrificing their time which is in itself a huge donation.
The same is of course true for the instructors.


I would put the introduction to log viewer and Python console into an earlier unit.
It's fun, it's practical and a major toolkit for all follow-ups.

Robert

> Cheers,

Joseph



From: nvda-addons@nvda-addons.groups.io
[mailto:nvda-addons@nvda-addons.groups.io] On Behalf Of Jaffar Sidek
Sent: Saturday, August 19, 2017 9:20 PM
To: nvda-addons@nvda-addons.groups.io
Subject: Re: [nvda-addons] Request for comments: an outline of a
complete course on NVDA internals and code contributions



Are these courses completely free? I am just wondering if some
donation could be asked for from those interested in the course, and
the donation could be used to fund NVDA. After all, This is an NVDA
project and As I see it, The whole course not only encompasses NVDA
but python programming in part. Just a thought to consider to help
fund NVDA.



On 20/8/2017 7:44 AM, Joseph Lee wrote:

Hi everyone,



Those of you on the users list may have heard about a subgroup over
there that aims to teach people how to contribute code to NVDA. After
going over some membership intros and looking at skill sets
represented, I came up with a rough outline or a six to twelve month
course on NVDA code contributions and internals. Obviously most of the
course content will require working knowledge of Python, but for those
who lack this, I've included a one unit outline on Python.



Outline:



* Title: So you want to improve NVDA with code contributions?
* Instructor: one or more NVDA experts and developers, along with
several Python users as tutors
* Purpose: the overall purpose of this course is to equip new
developers with knowledge required to provide code contributions to
NVDA project. Topics covered include a short review of Python, running
NVDA from source code, source code layout and overall architecture,
behind the scenes tour of features and commands, as well as things
required when contributing code such as identifying, designing,
coding, debugging, testing, submitting, maintaining, and explaining
new features, changes and bug fixes.
* Goals: have a working knowledge of Python so students can use it in
NVDA and other projects; learn the overall purpose and architecture of
NVDA; have knowledge of workings of features and commands through
reading, understanding and writing source code; learn tips for
becoming successful NVDA code contributors who serves the community
and improves NVDA; develop critical problem solving and thinking
skills required in today's software engineering projects including
that of NVDA.



Course outline:



Unit 0: Review of Python

1. Python is a general-purpose programming language
2. Downloading and using Python
3. Explain variables, how to import useful modules, conditionals and
loops
4. Learn how to define functions.
5. Design classes and objects
6. Learn to interact with lists, dictionaries, sets, tuples and other
objects of interest
7. Use modules and objects provided by Python to solve various problems
8. Exercise: random walk on a treadmill
9. Expected duration: four to six months



Skills test and preview 0: come up with solutions to two other
problems via Python, write a design for an add-on, or write about how
a student would solve an NVDA issue on GitHub.



Unit 1: Basics and the big picture

1. What screen readers are and are not
2. A portrait of operations of a screen reader
3. A brief history of NVDA
4. Obtaining NVDA source code
5. Compiling NVDA's source code with dependencies
6. Running NVDA from source for the first time
7. Example of code contribution: command to restart NVDA with no
prompts
8. Expected duration: one month



Skills test and preview 1: explain in your own words how you would
teach your friend to download NVDA source code.



Unit 2: NVDA at a glance

1. Features overview
2. Source code layout
3. Overall architecture
4. Importance of objects, events, and modules
5. Extensibility through classes
6. Why accessibility API's matter
7. Exercise: what is the code responsible for announcing speech via
beeps?
8. Example of code contribution: Popping up browse mode window for some
NVDA messages
9. Expected duration: two months



Skills test and preview 2: in your own words, describe ui.message function.



Unit 3: feature and command internals 1

1. Global commands
2. Focus, caret, system cursor
3. Object navigation, properties, developer information and object
hierarchy
4. Accessibility API's
5. Review cursor and text infos
6. Keyboard, mouse, and touchscreen
7. Basics of browse mode
8. Exercise: explain how NvDA+T command works to a new user
9. Example of code contribution: indentation announcement by tones
10. Expected duration: two to three months



Skills test and preview 3: in your own words, describe either one
property of a navigator object or how a first letter navigation
command works in browse mode.



Unit 4: Feature and command internals 2

1. App modules, global plugins and add-ons
2. Speech, braille, and tones
3. Synthesizers and braille displays
4. Math presentation layer and content recognition framework
5. NVDA dialogs, configuration management, and managing add-ons
6. Exercise: track down bugs in speech synthesizers
7. Example of code contribution: Unicode braille output
8. Expected duration: two months



Skills test and preview 4: in your own words, define what a speech
synthesizer driver is.



Unit 5: Code contributions

1. Identifying issues and suggestions
2. Designing a problem and its solution(s)
3. Coding a solution
4. Debugging and testing solutions
5. Effective use of log viewer and Python Console
6. Submitting, maintaining, and explaining a feature, a change, or a
bug fix
7. Exercise: not all warnings from the log are fatal
8. Example of code contribution: tab completion in Python Console
9. Expected duration: two to three months



Skills test and preview 5: write a solution for a minor issue on
GitHub or a small add-on that uses any concept from previous units.



Unit 6: Beyond code contributions

1. Translations
2. Documentation
3. Keep in touch with users and others in the community
4. Researching new ideas alone or in groups
5. Working on collaborative projects
6. Apply skills from NVDA to other projects
7. Exercise: write an article explaining inner workings of a community
add-on
8. Example of code contribution: Liblouis project
9. Expected duration: one month



Unit 7 (advanced): thinking outside of NVDA

1. Windows API
2. Python libraries
3. Dependency checks
4. Using Component Object Model
5. Using advanced features of accessibility API's
6. Adding new math presentation layers and content recognition
frameworks
7. Troubleshooting braille input and output
8. Engaging with the wider python and programming communities
9. Ethical issues in code contributions
10. Things to think about when leading or working on an international
software project



Final skills test:

1. From a set of problems dealing with Python, write solutions for two
and provide an explanation for one of them.
2. Write an NVDA add-on that utilizes at least two concepts described
in one or more units.
3. For a major NVDA GitHub issue, identify, design, code, debug, test,
submit, maintain, and explain a solution.



I expect the minimum time to complete this course would be six months
(excluding Python intros and advanced topics), with most people taking
up to a year to master the concepts above and become comfortable while
providing basic code contributions. The Python version to be employed
will be a mixture of 2.7 and 3.6.



Comments are appreciated.

Cheers,

Joseph





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