toggle quoted messageShow quoted text
Agreed (that’s one of the reasons why I comment a lot in my add-on source code).
One holiday wish I have (possibly a long-term wish) is to help folks get started on revamping the NVDA community documentation. At least this can include add-on user guides, but I foresee a day where the screen reader user guide would not escape this rewrite in hopes of making it more relevant for users. I would go so far as ask NVDA code contributors to add extensive documentation in source code itself – it is now possible to do it easily with help from a module called Sphinx, a source code based documentation generator. There are major issues to consider, however:
- Who is the target audience: thinking about this changes the game, as it will dictate tone, style, word usage, and organization of the document and supplemental materials.
- Mindset of code contributors: are we just software developers or technical authors? Some people would argue that developers should focus on programming and testing, leaving the task of documenting what developers wrote to technical authors, and this separation of concerns may foster better communication amongst team members. On the other hand, by forcing developers to become technical authors, they can make crucial decisions about the user-visible aspects of a given product a bit early.
- How can we show we accept diversity in terms of culture, language, skill level, and other factors: although the community documentation was written by NV Access people at first, it is increasingly written by people from diverse backgrounds in terms of culture, language, skill level, and other factors (although I did receive training on technical communication and software development, I’m not a native English speaker). This is more so for parts that are written by people who may have different interpretation about a UI message or concepts, more so if the author’s native language is not English (the reverse is true for translators as they need to grasp concepts written in English in their native languages).
My responses to the above questions are:
- Who is the target audience: it varies. For NVDA user guide, it is users with differing skill levels. For add-on guides, they target end users. For this reason, whenever I edit the NVDA user guide or add-on guides, I think about what users expect and NVDA’s response. This changes if we’re dealing with a document meant for developers (such as add-on internals and such).
- Mindset of code contributors: I believe that, as much as programming skills is important, willingness to communicate with audiences (users, other contributors, industry experts, etc.) is also important. One way to practice both is thinking and writing to and about users, therefore I tend to fall into a bit of the latter category from above: programming is, in one way or another, writing. Python is just one of the more specialized languages used to communicate with another entity (the machine), and if one can teach a computer to do something (along with fixing mistakes), it would be possible to train developers to respect users more by writing good documentation (of course someone may need to look at the documentation for style and such). My philosophy partly stems from my experiences as a former computer science major at a college I attended (different from the one I’m about to graduate from): my first computer science professor stressed the importance of source code comments and documentation, and I still practice this lesson today, which fuels my overall frustration with the current state of NVDA user guide and source code documentation in general. I think one exercise code contributors can do before submitting anything to GitHub (specifically, pull; requests) is writing an early user facing documentation, because doing so helps you improve your writing skills and think carefully about the impact of your changes when users meet them (I sometimes find myself struggling for minutes to hours over UI messages and documentation for this reason; I know what my code will do, but I hit a roadblock when explaining what I’ve done to would-be users before actually writing code).
- How can we show we are a group of people coming from diverse backgrounds: I think this goal was somewhat achieved when we look at recent NVDA work – many new features and bug fixes included in NVDA 2020.3 were written by someone other than an NV Access staff member, from people living in different countries and speaking many languages. But I know that we can improve on that somehow.
Another wish I have, mostly for Quentin: can we develop some sort of a training program for would-be contributors wishing to improve the overall NVDA community documentation, including the user guide? It may include basics on technical writing, tone and style, audience analysis, exercises where coding and documentation should be done together, and documentation production in a variety of formats (including online media). I think this may help us dive deeper into user guide issues being brought up, including the guide being “too thick” for newbies (in terms of understanding, lack of solid examples, and friendliness), especially for preferences chapter.
firstname.lastname@example.org <email@example.com> On Behalf Of
Sunday, October 18, 2020 11:56 AMTo:
Re: [nvda] NVDA Settings Documentation
While I applaud your efforts, and tutorials are invaluable, I wasn't even going that far. I'm talking basic documentation, where each item in a panel/pane/settings group in a given pane are briefly documented. There are myriad NVDA settings that, if their actual function is not directly obvious, which is the case, for example, with most checkboxes, then they're a black hole.
Even I will admit that for all software it is a limited number of end users who refer to this sort of thing. That being said, some do, and it serves as a very important basis for new developers to develop depth of knowledge of "what's in there and what it's for."
I was just commenting to someone for whom I've done custom VBA scripting for Outlook that I am eternally grateful to myself for having developed the habit of rigorously commenting my code, at a bare minimum, as even I would have no idea what some of what I've written actually does when looking at it much later. Complex stuff doesn't remain in "off the top of my head" mode (for most "mes") as time moves on. That's one of the reasons that basic documentation is so important.
Brian - Windows 10 Pro, 64-Bit, Version 2004, Build 19041
It’s hard waking up and realizing it’s not always black and white.
~ Kelley Boorn