Topics

[nvda-addons] Add-on development guide: terminology changes, Python 3 examples are being added

Luke Davis
 

On Thu, 31 Oct 2019, Joseph Lee wrote:

As the original author of NVDA Add-on development Guide, I would like to take this time to thank everyone for honest (and blunt) comments about terminology
going forward. Based on community feedback, the upcoming edition of NVDA Add-on Development Guide (this weekend) will include terminology changes as
follows:
Joseph. With respect, I'm not sure that less than ten messages, and less than 24 hours of conversation, can really count as completed community feedback. I feel like this is a hasty reaction, and we don't have to start setting things in stone, issuing effective dates, new terms, and so on just yet.

Anyway, if feedback is still welcome, than I submit the below.

The difference between “plugin” and “add-on” will be clarified, along with noting a history of how they came to be known. For future reference, the
Good. I think that is the thing we all seem to agree on. I was going to do so last night, but after your message I was afraid to make any changes for further evaluation.

definitions to be used (taking effect on January 1, 2020) will be:

* Add-on: a package for NVDA that includes one or more components for enhancing support for an app, a speech synthesizer, or a braille display, along with
global features and vision enhancement providers.
Personally, I am not convinced of the idea of introducing yet another term: components.

* Plugin: a module that modifies NVDA’s functionality, including adding support for a new app or a global feature.
I'm not fond of using the word module here, at least not unqualified.
A Python module, maybe. Unless you disagree about trying to use the more Pythonic definition of module.

* Component: another name for “plugin”, although this term will include things such as support components.
To me, this only seems to muddy the waters even more.
Do we really need this new term in the mix?

Honestly, how I would have done this whole thing would probably be more along the lines of the below (first draft):

* Add-on: a package for NVDA that contains one or more plugins or drivers, and all of their associated files and folders.

* Plugin: one or more Python modules, Windows libraries, or executables that modify NVDA's functionality. A plugin can add a global feature, add support for an app, or can supply a vision enhancement provider.

* Driver: a plugin which supports a speech synthesizer or a braille display.

* Enhancer: a plugin that works in tandem with NVDA in order to enhance usability of computer systems. Currently vision enhancement provider is the only Enhancer.

* Vision enhancement provider: a type of enhancer that allows people with varying sight to use computers more efficiently with help from NVDA. These include highlight tracking, screen curtain, magnification, and other possibilities.

I am not entirely pleased with the last two. Not sure we need Enhancer as a separate category of thing while there is only one kind, and it could be better explained than we have yet done.

Luke

Julien Cochuyt
 

Dear all,

Sorry to nitpick, but:
- NVDA plugins are not restricted to be Python modules: They can also be Python packages.
- The term plugin might not fit well braille display drivers, synth drivers and vision enhancement providers in that none of them get reloaded by the "Reload plugins" command in the "Tools" menu.

Best regards,

Julien Cochuyt
Accessolutions


Le ven. 1 nov. 2019 à 10:34, Luke Davis <luke@...> a écrit :
On Thu, 31 Oct 2019, Joseph Lee wrote:

> As the original author of NVDA Add-on development Guide, I would like to take this time to thank everyone for honest (and blunt) comments about terminology
> going forward. Based on community feedback, the upcoming edition of NVDA Add-on Development Guide (this weekend) will include terminology changes as
> follows:

Joseph. With respect, I'm not sure that less than ten messages, and less than 24
hours of conversation, can really count as completed community feedback. I feel
like this is a hasty reaction, and we don't have to start setting things in
stone, issuing effective dates, new terms, and so on just yet.

Anyway, if feedback is still welcome, than I submit the below.

> The difference between “plugin” and “add-on” will be clarified, along with noting a history of how they came to be known. For future reference, the

Good. I think that is the thing we all seem to agree on. I was going to do so
last night, but after your message I was afraid to make any changes for further
evaluation.

> definitions to be used (taking effect on January 1, 2020) will be:
>
>  *  Add-on: a package for NVDA that includes one or more components for enhancing support for an app, a speech synthesizer, or a braille display, along with
>     global features and vision enhancement providers.

Personally, I am not convinced of the idea of introducing yet another term:
components.

>  *  Plugin: a module that modifies NVDA’s functionality, including adding support for a new app or a global feature.

I'm not fond of using the word module here, at least not unqualified.
A Python module, maybe. Unless you disagree about trying to use the more
Pythonic definition of module.

>  *  Component: another name for “plugin”, although this term will include things such as support components.

To me, this only seems to muddy the waters even more.
Do we really need this new term in the mix?

Honestly, how I would have done this whole thing would probably be more along
the lines of the below (first draft):

* Add-on: a package for NVDA that contains one or more plugins or drivers, and
all of their associated files and folders.

* Plugin: one or more Python modules, Windows libraries, or executables that
modify NVDA's functionality. A plugin can add a global feature, add support for
an app, or can supply a vision enhancement provider.

* Driver: a plugin which supports a speech synthesizer or a braille display.

*  Enhancer: a plugin that works in tandem with NVDA in order to enhance
usability of computer systems. Currently vision enhancement provider is the only
Enhancer.

* Vision enhancement provider: a type of enhancer that allows people with
varying sight to use computers more efficiently with help from NVDA. These
include highlight tracking, screen curtain, magnification, and other possibilities.

I am not entirely pleased with the last two. Not sure we need Enhancer as a
separate category of thing while there is only one kind, and it could be better
explained than we have yet done.

Luke



Noelia Ruiz
 

DearJulien, thanks for this clarification distinguishing between plugins and drivers.
Cheers

El 01/11/2019 a las 14:06, Julien Cochuyt escribió:
Dear all,
Sorry to nitpick, but:
- NVDA plugins are not restricted to be Python modules: They can also be Python packages.
- The term plugin might not fit well braille display drivers, synth drivers and vision enhancement providers in that none of them get reloaded by the "Reload plugins" command in the "Tools" menu.
Best regards,
Julien Cochuyt
Accessolutions
Le ven. 1 nov. 2019 à 10:34, Luke Davis <luke@... <mailto:luke@...>> a écrit :
On Thu, 31 Oct 2019, Joseph Lee wrote:

> As the original author of NVDA Add-on development Guide, I would
like to take this time to thank everyone for honest (and blunt)
comments about terminology
> going forward. Based on community feedback, the upcoming edition
of NVDA Add-on Development Guide (this weekend) will include
terminology changes as
> follows:
Joseph. With respect, I'm not sure that less than ten messages, and
less than 24
hours of conversation, can really count as completed community
feedback. I feel
like this is a hasty reaction, and we don't have to start setting
things in
stone, issuing effective dates, new terms, and so on just yet.
Anyway, if feedback is still welcome, than I submit the below.

> The difference between “plugin” and “add-on” will be clarified,
along with noting a history of how they came to be known. For future
reference, the
Good. I think that is the thing we all seem to agree on. I was going
to do so
last night, but after your message I was afraid to make any changes
for further
evaluation.

> definitions to be used (taking effect on January 1, 2020) will be:
>
>  *  Add-on: a package for NVDA that includes one or more
components for enhancing support for an app, a speech synthesizer,
or a braille display, along with
>     global features and vision enhancement providers.
Personally, I am not convinced of the idea of introducing yet
another term:
components.

>  *  Plugin: a module that modifies NVDA’s functionality,
including adding support for a new app or a global feature.
I'm not fond of using the word module here, at least not unqualified.
A Python module, maybe. Unless you disagree about trying to use the
more
Pythonic definition of module.

>  *  Component: another name for “plugin”, although this term will
include things such as support components.
To me, this only seems to muddy the waters even more.
Do we really need this new term in the mix?
Honestly, how I would have done this whole thing would probably be
more along
the lines of the below (first draft):
* Add-on: a package for NVDA that contains one or more plugins or
drivers, and
all of their associated files and folders.
* Plugin: one or more Python modules, Windows libraries, or
executables that
modify NVDA's functionality. A plugin can add a global feature, add
support for
an app, or can supply a vision enhancement provider.
* Driver: a plugin which supports a speech synthesizer or a braille
display.
*  Enhancer: a plugin that works in tandem with NVDA in order to
enhance
usability of computer systems. Currently vision enhancement provider
is the only
Enhancer.
* Vision enhancement provider: a type of enhancer that allows people
with
varying sight to use computers more efficiently with help from NVDA.
These
include highlight tracking, screen curtain, magnification, and other
possibilities.
I am not entirely pleased with the last two. Not sure we need
Enhancer as a
separate category of thing while there is only one kind, and it
could be better
explained than we have yet done.
Luke

 

Hi,
Feedback duration: our discussion yesterday was the latest feedback to come in after months of conversations about documentation - feedback on add-on development guide and NVDA's documentation has been going on for months (Travis can testify to that).
Regarding the term "enhancer": I put it in there in case we get more possibilities in the future.
Regarding the term "component": it is based on a note on translations.
Hope this helps.
Cheers,
Joseph

-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Luke Davis
Sent: Friday, November 1, 2019 2:35 AM
To: nvda-addons@nvda-addons.groups.io
Cc: nvda-devel@groups.io
Subject: Re: [nvda-devel] [nvda-addons] Add-on development guide: terminology changes, Python 3 examples are being added

On Thu, 31 Oct 2019, Joseph Lee wrote:

As the original author of NVDA Add-on development Guide, I would like
to take this time to thank everyone for honest (and blunt) comments
about terminology going forward. Based on community feedback, the
upcoming edition of NVDA Add-on Development Guide (this weekend) will
include terminology changes as
follows:
Joseph. With respect, I'm not sure that less than ten messages, and less than 24 hours of conversation, can really count as completed community feedback. I feel like this is a hasty reaction, and we don't have to start setting things in stone, issuing effective dates, new terms, and so on just yet.

Anyway, if feedback is still welcome, than I submit the below.

The difference between “plugin” and “add-on” will be clarified, along
with noting a history of how they came to be known. For future
reference, the
Good. I think that is the thing we all seem to agree on. I was going to do so last night, but after your message I was afraid to make any changes for further evaluation.

definitions to be used (taking effect on January 1, 2020) will be:

* Add-on: a package for NVDA that includes one or more components for enhancing support for an app, a speech synthesizer, or a braille display, along with
global features and vision enhancement providers.
Personally, I am not convinced of the idea of introducing yet another term:
components.

* Plugin: a module that modifies NVDA’s functionality, including adding support for a new app or a global feature.
I'm not fond of using the word module here, at least not unqualified.
A Python module, maybe. Unless you disagree about trying to use the more Pythonic definition of module.

* Component: another name for “plugin”, although this term will include things such as support components.
To me, this only seems to muddy the waters even more.
Do we really need this new term in the mix?

Honestly, how I would have done this whole thing would probably be more along the lines of the below (first draft):

* Add-on: a package for NVDA that contains one or more plugins or drivers, and all of their associated files and folders.

* Plugin: one or more Python modules, Windows libraries, or executables that modify NVDA's functionality. A plugin can add a global feature, add support for an app, or can supply a vision enhancement provider.

* Driver: a plugin which supports a speech synthesizer or a braille display.

* Enhancer: a plugin that works in tandem with NVDA in order to enhance usability of computer systems. Currently vision enhancement provider is the only Enhancer.

* Vision enhancement provider: a type of enhancer that allows people with varying sight to use computers more efficiently with help from NVDA. These include highlight tracking, screen curtain, magnification, and other possibilities.

I am not entirely pleased with the last two. Not sure we need Enhancer as a separate category of thing while there is only one kind, and it could be better explained than we have yet done.

Luke

Travis Siegel
 

I find myself in complete agreement with Luke here.  These terms make the most sense to me.

On 11/1/2019 5:34 AM, Luke Davis wrote:
On Thu, 31 Oct 2019, Joseph Lee wrote:

As the original author of NVDA Add-on development Guide, I would like to take this time to thank everyone for honest (and blunt) comments about terminology
going forward. Based on community feedback, the upcoming edition of NVDA Add-on Development Guide (this weekend) will include terminology changes as
follows:
Joseph. With respect, I'm not sure that less than ten messages, and less than 24 hours of conversation, can really count as completed community feedback. I feel like this is a hasty reaction, and we don't have to start setting things in stone, issuing effective dates, new terms, and so on just yet.

Anyway, if feedback is still welcome, than I submit the below.

The difference between “plugin” and “add-on” will be clarified, along with noting a history of how they came to be known. For future reference, the
Good. I think that is the thing we all seem to agree on. I was going to do so last night, but after your message I was afraid to make any changes for further evaluation.

definitions to be used (taking effect on January 1, 2020) will be:

 *  Add-on: a package for NVDA that includes one or more components for enhancing support for an app, a speech synthesizer, or a braille display, along with
    global features and vision enhancement providers.
Personally, I am not convinced of the idea of introducing yet another term: components.

 *  Plugin: a module that modifies NVDA’s functionality, including adding support for a new app or a global feature.
I'm not fond of using the word module here, at least not unqualified.
A Python module, maybe. Unless you disagree about trying to use the more Pythonic definition of module.

 *  Component: another name for “plugin”, although this term will include things such as support components.
To me, this only seems to muddy the waters even more.
Do we really need this new term in the mix?

Honestly, how I would have done this whole thing would probably be more along the lines of the below (first draft):

* Add-on: a package for NVDA that contains one or more plugins or drivers, and all of their associated files and folders.

* Plugin: one or more Python modules, Windows libraries, or executables that modify NVDA's functionality. A plugin can add a global feature, add support for an app, or can supply a vision enhancement provider.

* Driver: a plugin which supports a speech synthesizer or a braille display.

*  Enhancer: a plugin that works in tandem with NVDA in order to enhance usability of computer systems. Currently vision enhancement provider is the only Enhancer.

* Vision enhancement provider: a type of enhancer that allows people with varying sight to use computers more efficiently with help from NVDA. These include highlight tracking, screen curtain, magnification, and other possibilities.

I am not entirely pleased with the last two. Not sure we need Enhancer as a separate category of thing while there is only one kind, and it could be better explained than we have yet done.

Luke

--
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus

 

Hi,
I see. If readers (including potential new readers) says this is better, then let's edit the guide to reflect that.
For Leonard: vision enhancement providers section is all yours - I wrote a preliminary version, but since you did the heavy work (with Reef), I think it'd be best if you can take care of that one.
To others: after thinking about community feedback on add-on development guide and personal reflection, I'm beginning to suspect gatekeeping is in full swing again - that is, only a few knowledgeable folks are writing the guide, with content based on their own understanding. I'm thinking this is contributing to the current state of NVDA's documentation. I bet we will have a philosophical discussion about it, but bluntly speaking, I'm in agreement with Travis on this - we need to do better, specifically as we see rise in development activity by third parties. I myself learned a great deal by reading the source code more carefully. This is why I have, and will continue to champion for improved documentation - add-on development guide was a good start with good intentions, but lately it isn't meeting the needs of audience members, and if this is indeed the case, this is a personal failure on my part (I take documentation seriously).
Regarding the gatekeeping bit: the more I think about current state of NVDA's documentation set, especially for ones targeting developers, I briefly wondered if I'm the one gatekeeping the process. If that's indeed the case (an answer that requires more thought and reflection), then I need to take another break from NVDA work, this time from touching anything and everything to do with documentation and reimagine how I deal with writing technical materials. A documentation is a contract and a gateway for people to get to know a product, and if edits must go through me (especially for a guide for add-on writers), a position where I can disregard needs of people without notice, then I need to step down completely.
Cheers,
Joseph

-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Travis Siegel
Sent: Friday, November 1, 2019 8:09 AM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] [nvda-addons] Add-on development guide: terminology changes, Python 3 examples are being added

I find myself in complete agreement with Luke here. These terms make the most sense to me.

On 11/1/2019 5:34 AM, Luke Davis wrote:
On Thu, 31 Oct 2019, Joseph Lee wrote:

As the original author of NVDA Add-on development Guide, I would like
to take this time to thank everyone for honest (and blunt) comments
about terminology going forward. Based on community feedback, the
upcoming edition of NVDA Add-on Development Guide (this weekend) will
include terminology changes as
follows:
Joseph. With respect, I'm not sure that less than ten messages, and
less than 24 hours of conversation, can really count as completed
community feedback. I feel like this is a hasty reaction, and we don't
have to start setting things in stone, issuing effective dates, new
terms, and so on just yet.

Anyway, if feedback is still welcome, than I submit the below.

The difference between “plugin” and “add-on” will be clarified, along
with noting a history of how they came to be known. For future
reference, the
Good. I think that is the thing we all seem to agree on. I was going
to do so last night, but after your message I was afraid to make any
changes for further evaluation.

definitions to be used (taking effect on January 1, 2020) will be:

* Add-on: a package for NVDA that includes one or more components
for enhancing support for an app, a speech synthesizer, or a braille
display, along with
global features and vision enhancement providers.
Personally, I am not convinced of the idea of introducing yet another
term: components.

* Plugin: a module that modifies NVDA’s functionality, including
adding support for a new app or a global feature.
I'm not fond of using the word module here, at least not unqualified.
A Python module, maybe. Unless you disagree about trying to use the
more Pythonic definition of module.

* Component: another name for “plugin”, although this term will
include things such as support components.
To me, this only seems to muddy the waters even more.
Do we really need this new term in the mix?

Honestly, how I would have done this whole thing would probably be
more along the lines of the below (first draft):

* Add-on: a package for NVDA that contains one or more plugins or
drivers, and all of their associated files and folders.

* Plugin: one or more Python modules, Windows libraries, or
executables that modify NVDA's functionality. A plugin can add a
global feature, add support for an app, or can supply a vision
enhancement provider.

* Driver: a plugin which supports a speech synthesizer or a braille
display.

* Enhancer: a plugin that works in tandem with NVDA in order to
enhance usability of computer systems. Currently vision enhancement
provider is the only Enhancer.

* Vision enhancement provider: a type of enhancer that allows people
with varying sight to use computers more efficiently with help from
NVDA. These include highlight tracking, screen curtain, magnification,
and other possibilities.

I am not entirely pleased with the last two. Not sure we need Enhancer
as a separate category of thing while there is only one kind, and it
could be better explained than we have yet done.

Luke


--
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus

 

I also agree with below people here:


* Avoid using the word component

* Try to talk about modules and packages in their pythonic meaning only to avoid confusion, don't use the word module interchangeably with plugin, add-on, etc. unless it's an NVDA appModule which the dev guide considers to be a plugin.


In current master, VisionEnhancementProvider inherrits from driver, but that will probably change when the gui is merged. Reef is mostly responsible for finishing the work on that now, I will be reviewing his huge and very valuable work next week. Long story short, vision enhancement providers will start to behave more like global plugins rather than drivers.


Regards,

Leonard

On 1-11-2019 16:09, Travis Siegel wrote:
I find myself in complete agreement with Luke here.  These terms make the most sense to me.

On 11/1/2019 5:34 AM, Luke Davis wrote:
On Thu, 31 Oct 2019, Joseph Lee wrote:

As the original author of NVDA Add-on development Guide, I would like to take this time to thank everyone for honest (and blunt) comments about terminology
going forward. Based on community feedback, the upcoming edition of NVDA Add-on Development Guide (this weekend) will include terminology changes as
follows:

Joseph. With respect, I'm not sure that less than ten messages, and less than 24 hours of conversation, can really count as completed community feedback. I feel like this is a hasty reaction, and we don't have to start setting things in stone, issuing effective dates, new terms, and so on just yet.

Anyway, if feedback is still welcome, than I submit the below.

The difference between “plugin” and “add-on” will be clarified, along with noting a history of how they came to be known. For future reference, the

Good. I think that is the thing we all seem to agree on. I was going to do so last night, but after your message I was afraid to make any changes for further evaluation.

definitions to be used (taking effect on January 1, 2020) will be:

 *  Add-on: a package for NVDA that includes one or more components for enhancing support for an app, a speech synthesizer, or a braille display, along with
    global features and vision enhancement providers.

Personally, I am not convinced of the idea of introducing yet another term: components.

 *  Plugin: a module that modifies NVDA’s functionality, including adding support for a new app or a global feature.

I'm not fond of using the word module here, at least not unqualified.
A Python module, maybe. Unless you disagree about trying to use the more Pythonic definition of module.

 *  Component: another name for “plugin”, although this term will include things such as support components.

To me, this only seems to muddy the waters even more.
Do we really need this new term in the mix?

Honestly, how I would have done this whole thing would probably be more along the lines of the below (first draft):

* Add-on: a package for NVDA that contains one or more plugins or drivers, and all of their associated files and folders.

* Plugin: one or more Python modules, Windows libraries, or executables that modify NVDA's functionality. A plugin can add a global feature, add support for an app, or can supply a vision enhancement provider.

* Driver: a plugin which supports a speech synthesizer or a braille display.

*  Enhancer: a plugin that works in tandem with NVDA in order to enhance usability of computer systems. Currently vision enhancement provider is the only Enhancer.

* Vision enhancement provider: a type of enhancer that allows people with varying sight to use computers more efficiently with help from NVDA. These include highlight tracking, screen curtain, magnification, and other possibilities.

I am not entirely pleased with the last two. Not sure we need Enhancer as a separate category of thing while there is only one kind, and it could be better explained than we have yet done.

Luke




Luke Davis
 

On Sat, 2 Nov 2019, Leonard de Ruijter wrote:

In current master, VisionEnhancementProvider inherrits from driver, but that will probably change when the gui is merged. Reef is mostly responsible for
finishing the work on that now, I will be reviewing his huge and very valuable work next week. Long story short, vision enhancement providers will start to
behave more like global plugins rather than drivers.
Will they be reloaded with the plugins reload command? As Julien pointed out, they aren't currently, as aren't drivers.

Luke