[NFBCS] FW: [program-l] Preliminary announcement: invitation to help out with Project Alexandria - improving NVDA's source code documentation in 2020

[Rasmussen, Lloyd]

From: program-l-bounce at freelists.org <program-l-bounce at freelists.org> On Behalf Of Joseph Lee
Sent: Saturday, January 04, 2020 10:12 PM
To: program-l at freelists.org
Subject: [program-l] Preliminary announcement: invitation to help out with Project Alexandria - improving NVDA's source code documentation in 2020

Hi all,

I tend to be a lurker, but I figured the following invitation would be relevant for folks on this forum:

As some of you may have heard, the NVDA community is currently in the midst of a Python 2 to 3 transition. As part of this, NVDA developers are looking into modernizing NVDA's documentation with Sphinx after discovering that Epydoc isn't compatible with recent Python 3 releases. There is even a branch to let Sphinx generate NVDA source code documentation.

Also, as some of you have discovered, when one tries to become an NVDA developer or write NVDA add-ons, the process is difficult than you initially thought (you need to learn Python and some additional things). This is made more difficult because source code documentation is incomplete - there are modules with no docstring whatsoever, or if they exist, they haven't been updated in a while.

To resolve documentation issues (or rather, incomplete source code documentation), I have formally launched Project Alexandria. The overall goal of this project (the codename refers to ancient Library of Alexandria in Egypt) 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. The end result will be a documentation that can help new developers, and also improves NVDA's value as a research artifact for researchers in various fields. This will be done by incorporating Sphinx, as well as seeking wisdom from people inside and outside of NVDA project regarding documentation process and mindset.

To coordinate this effort, a dedicated mailing list has been created through Groups.IO (named nvda-devdocs), which can be found at:
https://groups.io/g/nvda-devdocs

There are three reasons for posting the announcement here: to recruit project participants, to get your guidance and wisdom about this project, and to be directed to people who can help this effort. I believe what distinguishes a good project from an ordinary project is solid documentation, and I hope that folks here are in a position to make NVDA a better project through source code documentation. Even though I'm an experienced NVDA contributor, there are things I may not know about documentation, so I felt it would be best to seek your guidance. I cannot lead Project Alexandria alone, so I would like to connect with people who can lend a hand in this effort.

Special invitation for college students on this list: if it wasn't for NVDA work, I wouldn't have understood certain intricacies of computer programming as a college student (back in 2012, I joined NVDA project as a college student). I believe one way for you to improve your learning experience is using your skills to give back to a community. I know some of you are using NVDA for various tasks. I challenge you, therefore, please help out and give back to the community that gave you a screen reader you cannot live without by participating in Project Alexandria. Make NVDA's source code documentation understandable not only for yourselves, but also people who will follow after you.

If you have any questions or comments, feel free to contact me directly (you can reach me via email, or through Twitter at @joslee or Facebook via @josephsl). Thanks.
Cheers,
Joseph