[Python-ideas] Does jargon make learning more difficult?
Stephen J. Turnbull
turnbull.stephen.fw at u.tsukuba.ac.jp
Sun Aug 19 10:39:28 EDT 2018
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.
More information about the Python-ideas
mailing list