Topics

Add-on development guide: let us remove the one found on add-ons community website in favor of GitHub version

 

Hi all,

 

Some of you may see this message up to three times – that’s the beauty and a curse of blind carbon copies.

 

There was a question raised on the add-ons list regarding where to find the add-on development guide. At the moment the one that appears from Google search is:

https://addons.nvda-project.org/devDocs/devDocs.en.html

 

However, the most up-to-date version can be found here:

https://github.com/nvdaaddons/DevGuide/wiki/NVDA-Add-on-Development-Guide

 

I propose that we start referring to the second link. Although the first one has been translated into several languages, it is very out of date, as the last revision was in 2016 and hasn’t been updated ever since and won’t be updated at all. Although the second one is very up to date, it hasn’t been translated yet (personally I prefer to keep the guide in English, but I’m open to other possibilities). The biggest advantage of the second one is support for tables, and the fact that this is a wiki document that is also ready for revisions through Git make it a more attractive option.

 

Note that even though I am the author of the add-on development guide, it is still subject to community-based revisions. Also, Project Threshold is slowly being planned, which will make the first link obsolete. Therefore, you are more than welcome to provide feedback as to what to do until a few days after Threshold is launched, at which point backwards incompatible changes from my side (in this case, the link for the add-on development guide) will be locked.

 

Thank you.

Cheers,

Joseph

Tage Johansson
 

Hi,


I agree with you. It is only confusing to have two addon development guides, and I was actually confused myself the first time I googled which one to pick.


If someone really want to translate it then they can of course do that, but I think it is better to have an up to date guide in english than an out dated in many languages.


Best regards,

Tage


On 5/14/2019 12:55 AM, Joseph Lee wrote:

Hi all,

 

Some of you may see this message up to three times – that’s the beauty and a curse of blind carbon copies.

 

There was a question raised on the add-ons list regarding where to find the add-on development guide. At the moment the one that appears from Google search is:

https://addons.nvda-project.org/devDocs/devDocs.en.html

 

However, the most up-to-date version can be found here:

https://github.com/nvdaaddons/DevGuide/wiki/NVDA-Add-on-Development-Guide

 

I propose that we start referring to the second link. Although the first one has been translated into several languages, it is very out of date, as the last revision was in 2016 and hasn’t been updated ever since and won’t be updated at all. Although the second one is very up to date, it hasn’t been translated yet (personally I prefer to keep the guide in English, but I’m open to other possibilities). The biggest advantage of the second one is support for tables, and the fact that this is a wiki document that is also ready for revisions through Git make it a more attractive option.

 

Note that even though I am the author of the add-on development guide, it is still subject to community-based revisions. Also, Project Threshold is slowly being planned, which will make the first link obsolete. Therefore, you are more than welcome to provide feedback as to what to do until a few days after Threshold is launched, at which point backwards incompatible changes from my side (in this case, the link for the add-on development guide) will be locked.

 

Thank you.

Cheers,

Joseph

Brian's Mail list account
 

Re the translations. Are there any parts of the guide that remain unchanged and could have their translations, say in a zip download somewhere should any prospective translators come along later.
Having said all that, it is going to be a very difficult task to keep such a document up to date even in one language, let lone several.
This is a not just a problem on nvda but on many projects where users can add to the functionality etc.
I directly am not going to use it, but if I do meet anyone who is pretty good at programming just having one place for resources generally will be easier to pass on to them I feel.
Brian

bglists@...
Sent via blueyonder.
Please address personal E-mail to:-
briang1@..., putting 'Brian Gaff'
in the display name field.
Newsgroup monitored: alt.comp.blind-users

----- Original Message -----
From: "Joseph Lee" <@joslee>
To: <nvda-devel@groups.io>
Sent: Monday, May 13, 2019 11:55 PM
Subject: [nvda-devel] Add-on development guide: let us remove the one found on add-ons community website in favor of GitHub version


Hi all,



Some of you may see this message up to three times - that's the beauty and a
curse of blind carbon copies.



There was a question raised on the add-ons list regarding where to find the
add-on development guide. At the moment the one that appears from Google
search is:

https://addons.nvda-project.org/devDocs/devDocs.en.html



However, the most up-to-date version can be found here:

https://github.com/nvdaaddons/DevGuide/wiki/NVDA-Add-on-Development-Guide



I propose that we start referring to the second link. Although the first one
has been translated into several languages, it is very out of date, as the
last revision was in 2016 and hasn't been updated ever since and won't be
updated at all. Although the second one is very up to date, it hasn't been
translated yet (personally I prefer to keep the guide in English, but I'm
open to other possibilities). The biggest advantage of the second one is
support for tables, and the fact that this is a wiki document that is also
ready for revisions through Git make it a more attractive option.



Note that even though I am the author of the add-on development guide, it is
still subject to community-based revisions. Also, Project Threshold is
slowly being planned, which will make the first link obsolete. Therefore,
you are more than welcome to provide feedback as to what to do until a few
days after Threshold is launched, at which point backwards incompatible
changes from my side (in this case, the link for the add-on development
guide) will be locked.



Thank you.

Cheers,

Joseph



Jim Homme
 

Hi,

How do we get this to happen? I also think that some parts of the Development Guide from NVAccess should go in this area. The content from NVAccess would help beginning add-on developers get started.

 

Jim

 

 

 

==========

Jim Homme

Digital Accessibility

Bender Consulting Services

412-787-8567

https://www.benderconsult.com/our%20services/hightest-accessible-technology-solutions

 

From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Tage Johansson via Groups.Io
Sent: Monday, May 13, 2019 11:49 PM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Add-on development guide: let us remove the one found on add-ons community website in favor of GitHub version

 

Hi,

 

I agree with you. It is only confusing to have two addon development guides, and I was actually confused myself the first time I googled which one to pick.

 

If someone really want to translate it then they can of course do that, but I think it is better to have an up to date guide in english than an out dated in many languages.

 

Best regards,

Tage

 

On 5/14/2019 12:55 AM, Joseph Lee wrote:

Hi all,

 

Some of you may see this message up to three times – that’s the beauty and a curse of blind carbon copies.

 

There was a question raised on the add-ons list regarding where to find the add-on development guide. At the moment the one that appears from Google search is:

https://addons.nvda-project.org/devDocs/devDocs.en.html

 

However, the most up-to-date version can be found here:

https://github.com/nvdaaddons/DevGuide/wiki/NVDA-Add-on-Development-Guide

 

I propose that we start referring to the second link. Although the first one has been translated into several languages, it is very out of date, as the last revision was in 2016 and hasn’t been updated ever since and won’t be updated at all. Although the second one is very up to date, it hasn’t been translated yet (personally I prefer to keep the guide in English, but I’m open to other possibilities). The biggest advantage of the second one is support for tables, and the fact that this is a wiki document that is also ready for revisions through Git make it a more attractive option.

 

Note that even though I am the author of the add-on development guide, it is still subject to community-based revisions. Also, Project Threshold is slowly being planned, which will make the first link obsolete. Therefore, you are more than welcome to provide feedback as to what to do until a few days after Threshold is launched, at which point backwards incompatible changes from my side (in this case, the link for the add-on development guide) will be locked.

 

Thank you.

Cheers,

Joseph

derek riemer
 

Re translations: In order to do anything useful with NVDA development, you will need to understand english to read the documentation needed for development. This is more broad than just NVDA, a lot of programming is english centric. It is quite honestly a waste of our translators valuable time to translate the developer guide, because in order to really make the translations useful, the translator needs to have a solid understanding of the terms being used, many of which won't have equivelents in the translated language.

Re not knowing how to do certain things on github.
NVDA addon development is not a walk in the park, because people need to learn python. The project can spend time improving the product, and getting work done that will affect us all in amazing ways. We could also spend that time improving addon development guides, and other things, but ultimately, we use python for scripting, and with very good reasons. Any time we spend improving this process is time we are not able to spend working on the actual product. We can't do both. That being said, as new developers have come on board with the project, slowly people have been documenting what they found difficult, and improving the developer guides to make that useful. We are not trying to ignore the claims being made, but there are certain fundamental differences between NVDA addons and other screen reader scripts, and those differences were intentional choices made by the project in order to have a powerful scripting system. Some of those choices include having open wiki's that anyone, including everyone here, can maintain, and easing the burden on developers by storing those wikis in a place where they are automatically updated (github).

Jim Homme
 

Hi,

It sounds like it is OK for people like me to update the wiki. If this is OK, I will do all I can to be accurate. Do I need special permission to do this?

 

Thanks.

 

Jim

 

 

 

==========

Jim Homme

Digital Accessibility

Bender Consulting Services

412-787-8567

https://www.benderconsult.com/our%20services/hightest-accessible-technology-solutions

 

From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of derek riemer via Groups.Io
Sent: Tuesday, May 14, 2019 10:24 PM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Add-on development guide: let us remove the one found on add-ons community website in favor of GitHub version

 

Re translations: In order to do anything useful with NVDA development, you will need to understand english to read the documentation needed for development. This is more broad than just NVDA, a lot of programming is english centric. It is quite honestly a waste of our translators valuable time to translate the developer guide, because in order to really make the translations useful, the translator needs to have a solid understanding of the terms being used, many of which won't have equivelents in the translated language.

 

Re not knowing how to do certain things on github.

NVDA addon development is not a walk in the park, because people need to learn python. The project can spend time improving the product, and getting work done that will affect us all in amazing ways. We could also spend that time improving addon development guides, and other things, but ultimately, we use python for scripting, and with very good reasons. Any time we spend improving this process is time we are not able to spend working on the actual product. We can't do both. That being said, as new developers have come on board with the project, slowly people have been documenting what they found difficult, and improving the developer guides to make that useful. We are not trying to ignore the claims being made, but there are certain fundamental differences between NVDA addons and other screen reader scripts, and those differences were intentional choices made by the project in order to have a powerful scripting system. Some of those choices include having open wiki's that anyone, including everyone here, can maintain, and easing the burden on developers by storing those wikis in a place where they are automatically updated (github).