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

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~



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