Topics

Preliminary announcement: invitation for Project Alexandria - making NVDA source code documentation magnificent in 2020

 

Hello NVDA development community,

 

As some of you may have noticed (especially those watching GitHub and various NVDA forks), there is an active project to use Sphinx to generate NVDA source code documentation. This came about after discovering that the old system used to generate developer documentation (Epydoc) isn’t compatible with recent Python 3 releases. After doing some searching, several NVDA developers, including NV Access staff, decided to investigate Sphinx.

 

As an extension of this project, I would like to announce an initiative named Project Alexandria – making NVDA source code documentation magnificent in 2020. One of the issues raised by people new to NVDA and add-on development is incomplete source code documentation. While some modules and packages have useful documentation (such as UIA package), many modules do not, frustrating research by newbies. Lack of source code documentation also lowers NVDA’s potential for use by researchers in history, computer science, and disability studies, as screen reader source code docs is a good artifact for studying the history and trends in screen reading.

 

The project codename refers to Library of Alexandria, an ancient Egyptian library that housed thousands of books on all kinds of subjects. As such, the overall goal of this project is to transform NVDA’s source code documentation from a collection of incomplete shelves to a library filled with extensive, clear, effective, and teachable reading materials. This is realized through not only Sphinx, but also through generous “gifts” i.e. feedback from the public (developers, users, and even people outside of NVDA community) and mindset associated with making the documentation better and accessible.

 

To coordinate this project, a dedicated mailing list has been created on Groups.IO named nvda-devdocs. Some may say that it is better to create a subgroup of nvda-devel list to coordinate Alexandria. For people coming from programming background and for current members of this forum, subgroup creation would make sense, given that people need to be a member of this forum to become part of devdocs subgroup. But after reading articles on good documentation practices and philosophies, I realized that documenting source code of a large project such as NVDA require a lot of input from people outside of development sphere (including consulting documentation writers for other projects), hence a dedicated list was created. If a subgroup is desired, I propose a “devdocs” subgroup be created with permission from NV Access, but for now, a dedicated forum will be used.

 

The nvda-devdocs group can be found at:

https://groups.io/g/nvda-devdocs

 

Anyone interested in making NVDA source code documentation magnificent in 2020 and beyond are more than welcome to help out (this invitation is not only for developers, but also for add-on authors, users, and even folks outside of NVDA community); In particular, wisdom from users, documentation writers for projects outside of NVDA, and people wishing to use NVDA as a research artifact are welcome to join.

 

IMPORTANT: at the moment Sphinx workflow is not part of NVDA master source code branch, and NVDA people are working hard to make sure version 2019.3 is ready for everyone. Thus, I would like to suggest using this time to recruit people and plan for things ahead (planning ahead also means learning more about documentation process for various projects and mindset associated with it). I expect Alexandria to pick up speed after Sphinx work is merged into NVDA master branch.

 

Thank you.

Cheers,

Joseph~

Brian's Mail list account
 

Hi, I think I will keep off of that list since I do not fully understand what is proposed or why it is being proposed. I will say this though, in general, people who are learning about screenreaders find the jargon very mystifying, ie when we start talking about focus cart and various forms of controls that look the same but are not, I think combo boxes witch jump out on selection etc come to mind, so I can only comment that ats documentation really needs to be written by those creating the code. There does net to be a glossary of terms or at least some agreement on using the same terms for the same things. I have noticed this myself when looking at add onss, so I'd imagine the legacy of the code for NVDA itself has probably got multiple occurrences of the same but different problem. Grin.

Have you sent this to the user list as I'm not on it just now.
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: Sunday, January 05, 2020 2:28 AM
Subject: [nvda-devel] Preliminary announcement: invitation for Project Alexandria - making NVDA source code documentation magnificent in 2020


Hello NVDA development community,



As some of you may have noticed (especially those watching GitHub and
various NVDA forks), there is an active project to use Sphinx to generate
NVDA source code documentation. This came about after discovering that the
old system used to generate developer documentation (Epydoc) isn't
compatible with recent Python 3 releases. After doing some searching,
several NVDA developers, including NV Access staff, decided to investigate
Sphinx.



As an extension of this project, I would like to announce an initiative
named Project Alexandria - making NVDA source code documentation magnificent
in 2020. One of the issues raised by people new to NVDA and add-on
development is incomplete source code documentation. While some modules and
packages have useful documentation (such as UIA package), many modules do
not, frustrating research by newbies. Lack of source code documentation also
lowers NVDA's potential for use by researchers in history, computer science,
and disability studies, as screen reader source code docs is a good artifact
for studying the history and trends in screen reading.



The project codename refers to Library of Alexandria, an ancient Egyptian
library that housed thousands of books on all kinds of subjects. As such,
the overall goal of this project is to transform NVDA's source code
documentation from a collection of incomplete shelves to a library filled
with extensive, clear, effective, and teachable reading materials. This is
realized through not only Sphinx, but also through generous "gifts" i.e.
feedback from the public (developers, users, and even people outside of NVDA
community) and mindset associated with making the documentation better and
accessible.



To coordinate this project, a dedicated mailing list has been created on
Groups.IO named nvda-devdocs. Some may say that it is better to create a
subgroup of nvda-devel list to coordinate Alexandria. For people coming from
programming background and for current members of this forum, subgroup
creation would make sense, given that people need to be a member of this
forum to become part of devdocs subgroup. But after reading articles on good
documentation practices and philosophies, I realized that documenting source
code of a large project such as NVDA require a lot of input from people
outside of development sphere (including consulting documentation writers
for other projects), hence a dedicated list was created. If a subgroup is
desired, I propose a "devdocs" subgroup be created with permission from NV
Access, but for now, a dedicated forum will be used.



The nvda-devdocs group can be found at:

https://groups.io/g/nvda-devdocs



Anyone interested in making NVDA source code documentation magnificent in
2020 and beyond are more than welcome to help out (this invitation is not
only for developers, but also for add-on authors, users, and even folks
outside of NVDA community); In particular, wisdom from users, documentation
writers for projects outside of NVDA, and people wishing to use NVDA as a
research artifact are welcome to join.



IMPORTANT: at the moment Sphinx workflow is not part of NVDA master source
code branch, and NVDA people are working hard to make sure version 2019.3 is
ready for everyone. Thus, I would like to suggest using this time to recruit
people and plan for things ahead (planning ahead also means learning more
about documentation process for various projects and mindset associated with
it). I expect Alexandria to pick up speed after Sphinx work is merged into
NVDA master branch.



Thank you.

Cheers,

Joseph~



 

Hi,
The invitation won't be sent to users list until later until we get
confidence that those subscribed to devdocs list knows what they are doing -
source code level documentation is hard, requiring a specific mindset
(writing user guides is a bit harder, actually).
Cheers,
Joseph

-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Brian's Mail
list account via Groups.Io
Sent: Sunday, January 5, 2020 1:06 AM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Preliminary announcement: invitation for Project
Alexandria - making NVDA source code documentation magnificent in 2020

Hi, I think I will keep off of that list since I do not fully understand
what is proposed or why it is being proposed. I will say this though, in
general, people who are learning about screenreaders find the jargon very
mystifying, ie when we start talking about focus cart and various forms of
controls that look the same but are not, I think combo boxes witch jump out
on selection etc come to mind, so I can only comment that ats documentation
really needs to be written by those creating the code. There does net to be
a glossary of terms or at least some agreement on using the same terms for
the same things. I have noticed this myself when looking at add onss, so I'd
imagine the legacy of the code for NVDA itself has probably got multiple
occurrences of the same but different problem. Grin.

Have you sent this to the user list as I'm not on it just now.
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: Sunday, January 05, 2020 2:28 AM
Subject: [nvda-devel] Preliminary announcement: invitation for Project
Alexandria - making NVDA source code documentation magnificent in 2020


Hello NVDA development community,



As some of you may have noticed (especially those watching GitHub and
various NVDA forks), there is an active project to use Sphinx to
generate NVDA source code documentation. This came about after
discovering that the old system used to generate developer
documentation (Epydoc) isn't compatible with recent Python 3 releases.
After doing some searching, several NVDA developers, including NV
Access staff, decided to investigate Sphinx.



As an extension of this project, I would like to announce an
initiative named Project Alexandria - making NVDA source code
documentation magnificent in 2020. One of the issues raised by people
new to NVDA and add-on development is incomplete source code
documentation. While some modules and packages have useful
documentation (such as UIA package), many modules do not, frustrating
research by newbies. Lack of source code documentation also lowers
NVDA's potential for use by researchers in history, computer science,
and disability studies, as screen reader source code docs is a good
artifact for studying the history and trends in screen reading.



The project codename refers to Library of Alexandria, an ancient
Egyptian library that housed thousands of books on all kinds of
subjects. As such, the overall goal of this project is to transform
NVDA's source code documentation from a collection of incomplete
shelves to a library filled with extensive, clear, effective, and
teachable reading materials. This is realized through not only Sphinx, but
also through generous "gifts" i.e.
feedback from the public (developers, users, and even people outside
of NVDA
community) and mindset associated with making the documentation better
and accessible.



To coordinate this project, a dedicated mailing list has been created
on Groups.IO named nvda-devdocs. Some may say that it is better to
create a subgroup of nvda-devel list to coordinate Alexandria. For
people coming from programming background and for current members of
this forum, subgroup creation would make sense, given that people need
to be a member of this forum to become part of devdocs subgroup. But
after reading articles on good documentation practices and
philosophies, I realized that documenting source code of a large
project such as NVDA require a lot of input from people outside of
development sphere (including consulting documentation writers for
other projects), hence a dedicated list was created. If a subgroup is
desired, I propose a "devdocs" subgroup be created with permission
from NV Access, but for now, a dedicated forum will be used.



The nvda-devdocs group can be found at:

https://groups.io/g/nvda-devdocs



Anyone interested in making NVDA source code documentation magnificent
in
2020 and beyond are more than welcome to help out (this invitation is
not only for developers, but also for add-on authors, users, and even
folks outside of NVDA community); In particular, wisdom from users,
documentation writers for projects outside of NVDA, and people wishing
to use NVDA as a research artifact are welcome to join.



IMPORTANT: at the moment Sphinx workflow is not part of NVDA master
source code branch, and NVDA people are working hard to make sure
version 2019.3 is ready for everyone. Thus, I would like to suggest
using this time to recruit people and plan for things ahead (planning
ahead also means learning more about documentation process for various
projects and mindset associated with it). I expect Alexandria to pick
up speed after Sphinx work is merged into NVDA master branch.



Thank you.

Cheers,

Joseph~




Brian's Mail list account
 

Oh yes I know which was why I brought up the jargon issue for the documentation for the end user.
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: Sunday, January 05, 2020 3:24 PM
Subject: Re: [nvda-devel] Preliminary announcement: invitation for Project Alexandria - making NVDA source code documentation magnificent in 2020


Hi,
The invitation won't be sent to users list until later until we get
confidence that those subscribed to devdocs list knows what they are doing -
source code level documentation is hard, requiring a specific mindset
(writing user guides is a bit harder, actually).
Cheers,
Joseph

-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Brian's Mail
list account via Groups.Io
Sent: Sunday, January 5, 2020 1:06 AM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Preliminary announcement: invitation for Project
Alexandria - making NVDA source code documentation magnificent in 2020

Hi, I think I will keep off of that list since I do not fully understand
what is proposed or why it is being proposed. I will say this though, in
general, people who are learning about screenreaders find the jargon very
mystifying, ie when we start talking about focus cart and various forms of
controls that look the same but are not, I think combo boxes witch jump out
on selection etc come to mind, so I can only comment that ats documentation
really needs to be written by those creating the code. There does net to be
a glossary of terms or at least some agreement on using the same terms for
the same things. I have noticed this myself when looking at add onss, so I'd
imagine the legacy of the code for NVDA itself has probably got multiple
occurrences of the same but different problem. Grin.

Have you sent this to the user list as I'm not on it just now.
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: Sunday, January 05, 2020 2:28 AM
Subject: [nvda-devel] Preliminary announcement: invitation for Project
Alexandria - making NVDA source code documentation magnificent in 2020


Hello NVDA development community,



As some of you may have noticed (especially those watching GitHub and
various NVDA forks), there is an active project to use Sphinx to
generate NVDA source code documentation. This came about after
discovering that the old system used to generate developer
documentation (Epydoc) isn't compatible with recent Python 3 releases.
After doing some searching, several NVDA developers, including NV
Access staff, decided to investigate Sphinx.



As an extension of this project, I would like to announce an
initiative named Project Alexandria - making NVDA source code
documentation magnificent in 2020. One of the issues raised by people
new to NVDA and add-on development is incomplete source code
documentation. While some modules and packages have useful
documentation (such as UIA package), many modules do not, frustrating
research by newbies. Lack of source code documentation also lowers
NVDA's potential for use by researchers in history, computer science,
and disability studies, as screen reader source code docs is a good
artifact for studying the history and trends in screen reading.



The project codename refers to Library of Alexandria, an ancient
Egyptian library that housed thousands of books on all kinds of
subjects. As such, the overall goal of this project is to transform
NVDA's source code documentation from a collection of incomplete
shelves to a library filled with extensive, clear, effective, and
teachable reading materials. This is realized through not only Sphinx, but
also through generous "gifts" i.e.
feedback from the public (developers, users, and even people outside
of NVDA
community) and mindset associated with making the documentation better
and accessible.



To coordinate this project, a dedicated mailing list has been created
on Groups.IO named nvda-devdocs. Some may say that it is better to
create a subgroup of nvda-devel list to coordinate Alexandria. For
people coming from programming background and for current members of
this forum, subgroup creation would make sense, given that people need
to be a member of this forum to become part of devdocs subgroup. But
after reading articles on good documentation practices and
philosophies, I realized that documenting source code of a large
project such as NVDA require a lot of input from people outside of
development sphere (including consulting documentation writers for
other projects), hence a dedicated list was created. If a subgroup is
desired, I propose a "devdocs" subgroup be created with permission
from NV Access, but for now, a dedicated forum will be used.



The nvda-devdocs group can be found at:

https://groups.io/g/nvda-devdocs



Anyone interested in making NVDA source code documentation magnificent
in
2020 and beyond are more than welcome to help out (this invitation is
not only for developers, but also for add-on authors, users, and even
folks outside of NVDA community); In particular, wisdom from users,
documentation writers for projects outside of NVDA, and people wishing
to use NVDA as a research artifact are welcome to join.



IMPORTANT: at the moment Sphinx workflow is not part of NVDA master
source code branch, and NVDA people are working hard to make sure
version 2019.3 is ready for everyone. Thus, I would like to suggest
using this time to recruit people and plan for things ahead (planning
ahead also means learning more about documentation process for various
projects and mindset associated with it). I expect Alexandria to pick
up speed after Sphinx work is merged into NVDA master branch.



Thank you.

Cheers,

Joseph~