Re: 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~




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