tl;dr I don't think so, not very much. There are bigger fish to fry. I would appreciate comments on the last paragraph (before the footnotes), which can be read standalone. If opinion is at all favorable, I'll raise it with the PSF.
Jonathan Fine writes: > Summary: Discussion of the words 'jargon' and 'chatter'. Recommend > that we learn better how to find a compromise (strike a balance) > between precision and simplicity. I'm not a big fan of asking that everybody put such effort into documentation for code they're developing. IMHO, where available users should just buy books by professional writers written to their level, rather than imposing this burden on the software development project. Developers themselves should be asked to write concise, precise documentation. I don't think it's at all a good idea to burden them with "accessibility" issues. It's hard enough to write good notes for yourself a year hence! Tutorial writers, OK, they should be cautioned to avoid jargon, but if they aren't already judicious about using jargon, maybe they shouldn't be writing tutorials at all? What about documentation patches from users (including developers who didn't write the docs being edited)? In general, I favor restricting these to correcting bugs, missing information, and extremely convoluted syntax. If the docs use jargon (by which I mean "informal technical terms, often local to the project") which is intelligible to long-time users but may be off-putting to newcomers and infrequent users (of the documentation, not the software!), I think it is better to provide a glossary.[1] The problem with editing inline is that there are direct costs and a missed opportunity. The direct costs include the potential for introducing imprecision and outright documentation bugs, and code churn (increasing the cost of reading diffs). The missed opportunity is that a good glossary will also serve users who graduate to "informal write-only documentation" including archives of mailing lists and group chats, and the issue tracker. I'm not sure about the "conventional" accessibility issues (ie, excluding newcomers, non-native speakers, and translators). As a developer/maintainer I have had a small amount of contact with users with perceptual and motor disabilities, but have never heard them complain[2] about jargon. (Small sample, but before we presume they would benefit from simplified docs, we should consult experts.) Serving non-native-speakers is a tough call. On the one hand, they would be best served by good translations and glossaries of English jargon in their native language. You don't need to speak English at all to write good programs in programming languages based on English keywords, and the concepts are easier to understand, and precision easier to obtain, if you're not fighting with a second language. For many of my students, the first language is Chinese, the second Japanese, and the third English. English keywords and the occasional concept denoted by jargon don't faze them. The problem is more following simple directions about inserting punctuation, misspelled words, and so on -- the closest literal translations often are poor semantic matches, and so all English is awkward for them. But I can understand half (well, 10% ;-) of what their sempai are saying in Chinese, because of the keywords and borrowed jargon -- and so can the kohai. Jargon isn't a problem; it's just another symbol for an unfamiliar concept that they need to learn. On the other, we're not doing a good job of encouraging translators. There are a lot of volunteers in the translation community, and (like programmers) an important reward is getting their product into the distribution. (This is *not* a complaint about the Python maintainers. The costs of infrastructure and maintaining synchronization of translations with the original documentation are still quite high.) I suppose there must be corporations who are doing translations for their Python-based products, and we can do a better job of getting them to contribute them upstream (although we currently have the problem of "where is upstream?" since we don't distribute translations ourselves). Finally, before getting the project into the hairy maintenance issues that go with distributing translations, I suggest the PSF could buy the high-quality tutorial books and textbooks (and maybe dictionaries as well) for translators. Very cheap, but the symbolism that "somebody noticed, and they care!" is a big reward for many contributors. Another possibility would be complimentary tickets (and/or travel grants) to PyCon. From past experience I gather that many translators are more focused on their natural language than on the projects whose documentation they translate, so it's probably not worth sending them to big international PyCons to be lionized by the core developers and PSF board members. On the other hand going to a local PyCon might be attractive, especially if they got complimentary tickets to some of the parties, where they would be introduced to keynote speakers and the like, and would be lionized by the people they're writing for. Not to mention getting feedback. Steve Footnotes: [1] The convention in academic and textbook writing of providing definitions (and expansions of abbreviations and acronyms) at first use is a good one, but the glossary is essential in technical documentation because users frequently dip into the middle of a document for a specific entry rather than reading linearly. [2] In fact, users with disabilities rarely complain in my experience. They just point out their issues without attitude. _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
