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~

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