w3c
Identify and (explain or change) W3C jargon words
#455 reminded me of a recent thought: we should be very conscious of terms that have become W3C jargon, maybe without long-timers noticing, and that are not obvious to newcomers, and therefore make W3C a less welcoming environment.
For example one that I noticed recently, in the context of the editorial work in support of P2020 (respec if I remember rightly), is "living standard", which has become loaded with a lot of implications in W3C amongst those who have discussed Process. Everywhere else though, "living standards" is a phrase that refers to the quality of life of people! Even if you know you're thinking about a technical standard document, the idea of it being "alive" is something that needs more explanation.
Raising this issue as a question rather than a solution at this stage: is there a way to identify when usage of a word or phrase has gone so far beyond the "ordinary" meaning that it can be called jargon? Maybe we could we bring in a language expert to help us, since by the very nature of this issue, people following this repo's issues probably understands most of the jargon terms and is therefore not aware of when they need more explanation for those who do not.
I guess we could do a poll of some sort: "what terms did you first come across in W3C that you remember having to work to understand at first?"
@nigelmegitt Jargon is a huge issue in particular for people for whom English is not a first language. It might be useful to have some of the members of W3C whose native languages are not English provide some feedback.
I feel there's two sides to this coin. Non native speakers need to learn the vocabulary anyway, be it jargony or mainstream. Jargon is harder to find in dictionaries or to find explanations for when it is not documented. At the same time, it has happened to me reasonably often that I discover that a word which I thought was perfectly ordinary (due to hearing and using it all the time in w3c contexts) is actually a piece of jargon that is unrecognized by native speakers outside of this context, or which has a different meaning in other contexts. So in some cases, Jargon may actually be more confusing to native speakers.
We already have a page documenting our jargon: https://www.w3.org/2001/12/Glossary
However, I don't think it is well publicized or well maintained. It probably should be both.
We should move the Glossary to a place where it can be easily updated, and update it, and link from the Process to it, perhaps (informatively). But this is a team issue, not process, isn't it? Can we transfer it? Could we auto-build a glossary over W3C /TR and normative documents like the Process and Patent Policy?
Transfer to Team for Guidance docs?
Everywhere else though, "living standards" is a phrase that refers to the quality of life of people
FWIW, I've never encountered a use of "living standards" meant to have that meaning before this issue.
"Standard(s) of living" is the phrase I've heard used to refer to the quality of life of people.
When discussing standards such as W3C and IETF emit, i.e., in context, "living standards" seems most likely to have the meaning intended by those bodies; indeed, it's the interpretation I put on that phrase when I first encountered it.
Yes, "Living Standard" was coined by the WHATWG and it's perhaps not ideal, but it's the term now used by us and them for a standard that is in continual revision.
Could we auto-build a glossary over W3C /TR and normative documents like the Process and Patent Policy?
Bikeshed can generate that sort of things:
<index type="dfn"></index>
or, if you want to limit to a (set of) specific document(s)
<index type="dfn" spec="css-grid-1, svg2"></index>
For now, neither the Process nor the Patent Policy are indexed, but that's something we should fix, and I don't believe it to be hard, since they're already in the right format.
@tabatkins, (or maybe @plinss, or maybe @tobie) where do we file a bug (or a PR) to get https://www.w3.org/Consortium/Process/ and https://www.w3.org/Consortium/Patent-Policy/ indexed?
I'll put them into Shepherd; I'll assume w3c-process and w3c-patent-policy are appropriate shortnames.
Can you file a bug on https://github.com/w3c/browser-specs as well?
FWIW, I've never encountered a use of "living standards" meant to have that meaning before this issue.
@TallTed the request here is not for individual anecdotes, but for some way to generate/collect data to identify and mitigate potential exclusion through the use of jargon.
I'll put them into Shepherd; I'll assume w3c-process and w3c-patent-policy are appropriate shortnames.
Seems fair. We've been using them without the w3c- prefix, but if it goes into a bigger repo of things where disambiguation seems necessary, these are good shortnames.
Can you file a bug on https://github.com/w3c/browser-specs as well?
I don't mind doing it, but I am not familiar with that project, and reading up what it's supposed to be about, it doesn't seem to be a good fit. You probably know what you're talking about, but I don't, so filing a bug whose description is "Tab told me to file this, I don't know why" doesn't seem ideal.
Well, the reason is that I'll be switching Bikeshed over to using that as a data source any day now (well, the Reffy project, but it uses browser-specs to know what to crawl), and ReSpec already uses it as the data source, so if we're expecting these to be useful to link to from web specs, it should be in that repo.
It describes itself as a list of "technical Web specifications that are directly implemented or that will be implemented by Web browsers". That seems significantly narrower than the scope of W3C in general, which also a fair amount of specs that are meant to be implemented by things other than browsers, before we even start to think about things like Notes (or the Process). Is that statement stale, and they've since switched to a broader idea of what they'll support?
I suspect this issue should be closed in favor of https://github.com/w3c/AB-memberonly/issues/107
It's a valid concern, but maintaining the glossary is not part of the process, the the AB repo is a better host for this.
@frivoal that could work; 2 thoughts:
- Breadth of application: To the extent that jargon words are included in the Process, this is a Process issue, but I agree that it has broader application, and if the AB wants to own a project to identify jargon words and find a way to address their usage, either by changing to more easily understood terms or by explaining them, then that'd be good. I don't think it's clear yet if the AB does want to own such a project.
- Visibility: Since the communities I'm concerned may be excluded by use of jargon are by definition not involved in W3C, I'd like to know that any work here has public input, and the w3c/AB-memberonly repo is not public visible. Of course consideration of AB ownership of such a project can be a private W3C matter, while the inputs to the project can be public. We should be aware of the restriction of visibility of the discussion that would occur by closing this issue in favour of continuing the discussion elsewhere.
I'm not at all sure why we don't have bikeshed automatically do this across all bikeshed specs, taking people back to where terms are defined. Terms should be defined at source, and then replicated into a glossary that's hyperlinked to the source. We should not define out-of-line as that means that the glossary itself would be subject to AC review and director approval.
I'm not at all sure why we don't have bikeshed automatically do this
Gave it a try, but I'm blocked by https://github.com/tabatkins/bikeshed/issues/2317
While only a stub with limited content at the moment, the AB has published a semi-automated glossary. https://w3c.github.io/AB-public/Glossary I think we should close this, and any follow up issue should be filed against that Glossary.
The Revising W3C Process CG just discussed W3C Glossary, and agreed to the following:
-
RESOLVED: Close issue 456
The full IRC log of that discussion
<fantasai> Subtopic: W3C Glossary<fantasai> github: https://github.com/w3c/w3process/issues/456#issuecomment-2065824197
<fantasai> florian: Not great, but it exists and AB can publish as a NOTE
<fantasai> ... propose to close the issue, file follow-up against the AB
<fantasai> plh: makes sense to me
<fantasai> ... covers only Patent Policy and Process?
<fantasai> florian: It has a few parts, automated pull from Process and Patent Policy
<fantasai> ... also two manual sections, one where we link to relevant terms defined elsewhere
<fantasai> ... not every term in W3C, but ones that are widely relevant
<fantasai> ... and terms that are widely relevant but not defined elsewhere, can add into glossary
<fantasai> ... not good enough yet, but framework is there
<fantasai> plh: agree to close issue
<fantasai> ... anyone else?
<fantasai> <fantasai> +1
<fantasai> RESOLVED: Close issue 456
