NVDASR: diary of do's and don'ts in NVDA tickets, add-ons and what not

Hi,

One of the strengths of software development is ability for users and developers to participate in shaping a software. This is more important if this software is needed by the user (or users) for performing various tasks. But there are times when something comes up that makes programmers sigh and think, “hmmm, maybe I need to tell users how they can help me.” This is one of those posts, and for those who are NVDA (NonVisual Desktop Access) users, you might want to keep this in mind to help NVDA developers in understanding your needs. To address different user groups, I’ ve organized this post into sections so you can quickly jump to the desired section.

 

Filing issues

Bugs are bound to exist in any software project. Once a user finds a bug, he or she would tell the developer about the bug in hopes of getting it fixed.

For the most part, NVDA developers receive good amount of information about a bug when a user files a ticket (issue). However, there are times when programmers ask the user to provide more details such as version of the app, how to reproduce a problem and so on.

Here are some questions that might be asked when filing an issue with NVDA (or with any software):

·        Steps to reproduce a problem: Sometimes, a user may not write how to reproduce a problem (if it is a recurring one). Just saying “… this problem exists …” or “… NVDA should do this and that …” does not provide the picture the developers need. The first and important information to provide (besides other info such as version of the program you’re using) is the procedure to reproduce a problem. This includes commands you’ve tried, expected behavior, actual behavior and so on.

·        Is this specific to NVDA: a good way to test this is running multiple screen readers, with the user trying the problem steps with each screen reader. If ALL of them produce the same result, chances are that it might be the application that’s causing the issue. If the problem exists when NVDA is used, then the probability of this being an NVDA issue increases.

·        Program version: a problem with one version of a program may not mean the problem exists with other versions (more so in Office applications and web browsers). If possible, please test for the issue with more than one version of the program in hopes of narrowing down the problem to a specific version.

·        Do not paste the entire contents of your log file: if you need to paste a log fragment, try pasting only the relevant log fragment – that is, one minute prior to the start of the problem and up to one minute after, with the log level set to input/output from NVDA’s General Settings dialog.

·        Search the tickets before filing the issue: it is important to remember that a feature that you’re suggesting may have been suggested before, hence searching the ticket system before posting a brand new suggestion.

 

Add-ons:

One of the strengths of NVDA is add-ons, which allows programmers (and users) to extend NVDA’s functionality through Python modules.

Some do’s and don’ts about add-ons include:

·        Learn Python: add-ons are Python code, so it is essential that you know Python and can use it (write some programs in Python first before writing import addonHandler).

·        Get ready to write more English than Python: it may sound odd to say this, but throughout the life of your add-on, you’ll be talking with users, so be prepared to explain what you’re doing.

·        Get intimate with your target system: no, not love. I’m talking about being familiar with the app you’re writing the app module for, feature for which you’ll be writing your next global plug-in, and features of your speech synthesizer and braille display you wish NVDA users to use.

·        Invite your users along the ride: it is important to remember that your “passengers” (clients) are users who uses a particular app, a feature in NVDA, etc. Invite them along, listen to their suggestions, go through steps to reproduce bugs and what not.

·        Don’t use fancy routine unless if you know what you’re doing: it is better to keep the code simple and make it run instead of using fancy functions and break your add-on. If you want to make your add-on work faster, don’t do it until the very end (I might add, “don’t try it”) after you know for sure your add-on works as advertised i.e. works 100%.

·        Make a habit of visiting NVDA’s Python Console: test your routine in the console (especially if writing a routine in an app module) before writing your code in the add-on file.

·        Always debug with multiple scenarios: your add-on may only work for certain app versions, or your synthesizer may not pronounce things right. Always debug your add-ons with multiple scenarios (different versions of an app, different braille display models, etc.).

·        Most importantly, have fun.

That’s all for tonight. Hope this helps.