Wikipedia talk:Readability tools

"Link out"

I don't object to the presence of numerous links in the body of articles. That's the right place for them. But if I'm perusing the introductory section of an article, "linking out" within it will bring me to a dead stop, often repeatedly, if there are repeated links from unfamiliar or unknown words. The introduction will have failed its purpose: to provide an abbreviated, readable, comprehensible summary of the subject. Worse, is that in almost every case I've seen, the articles linked from an introduction contain their own collection of links from unfamiliar words to still more articles that--you guessed it--contain their own links from unfamiliar words to--you guessed it--more article introductions (with links!). The dictionary definition of ad infinitum should have a schematic image of Wikipedia's linking practice on the page. To sum it up--as perhaps you may have seen my comments on this issue at wp:MTAU--article introductions should stand on their own, use plain English, and not attempt to "educate" readers by needlessly shoveling jargon at them, forcing them to repeatedly stop reading the summary they came for and falling into a warren of other articles which contain further servings of jargon in their introductions. DonFB (talk) 06:59, 5 January 2025 (UTC)

What do you do if you encounter an unknown word, and it's not linked? WhatamIdoing (talk) 07:06, 5 January 2025 (UTC)

I look it up if I can't perceive the meaning from context. My argument is that jargon in the lede can be replaced by plain English most of the time. It is also possible to link the common word to the article which defines the jargon. That allows readers to continue uninterrupted but gives them the option to get more detail if they want. I would ask that you consider modifying this essay so it does not encourage editors to load up lede sections with potentially unfamiliar words simply because they can be linked. DonFB (talk) 01:37, 7 January 2025 (UTC)

How do you look it up? WhatamIdoing (talk) 18:01, 7 January 2025 (UTC)

I paste it into Google search box. Do you advocate using jargon freely in the lede section of articles? I note that in the discussion at Make Tech Articles Understandable, you recommended the Write One Level Down approach, which would probably result in less jargon. Again, my main concern is with lede sections, where minimum or no jargon is a good thing, because it makes that section--which may be the only part that a lot of people read--more readable.

Have a look at the article Snowclone. Before I edited it, the first sentence included "phrasal template", which was linked. I didn't recognize the term, and I think most people wouldn't. Hovering over it, I saw the first sentence of the 'phrasal template' article, which said: "A phrasal template is a phrase-long collocation...." "Collocation"? So I hovered over that and saw: "In corpus linguistics...", also linked. This kind of chain of inscrutable jargon in Wikipedia lede sections comes off almost as a practical joke. To repeat myself: I don't object to jargon and specialized terminology in the body of articles, but putting it into lede sections is a disservice to many readers, who are only looking for a brief, readable summary of a subject. DonFB (talk) 21:30, 7 January 2025 (UTC)

I prefer to look up unfamiliar words directly in Wikipedia when possible. Having a link makes that easier.

I think that whether we'd consider a word to be "jargon" or "technical" depends on the subject of the article. Additionally, whether the presence of (explained) jargon is desirable is going to vary by subject. If you're trying to decode a medical test, then you need the jargon to be visible in the text of the article. If the reader is trying to figure out what the word hyperlipidemia means on their report, then hiding that word under the simple, readable, and jargon-free description of "high level of fat in the blood" does not help the reader meet their actual needs. WhatamIdoing (talk) 23:27, 7 January 2025 (UTC)

My perspective is that of an average Wikipedia reader who wants information, but perhaps not deep detail, about a subject that is either unfamiliar, or recognized but little known. I suppose some people may use Wikipedia to help understand a personal medical condition, but that seems a little scary, frankly. The example you cited is largely acceptable, because the intro does a good job explaining the terms. In many cases, however, editors simply toss jargon into the introduction with no explanatory text, because they have academic knowledge of the subject, and it's easier for them to use jargon they've learned than to make an effort to provide a brief plain English definition or explanation. In short, they're not taking the readership into consideration. They are focused only on spilling their specialized knowledge and terminology onto the page without regard for who the readers may be. Those are the cases I'm talking about, and they are legion. Yes, it's quicker to click a Wikipedia link than to look up in Google, but my point is that jargon in the lede can be eliminated, minimized, or supplemented with a brief plain English definition or explanation, so there would be no need to stop reading and look up anything. As others have noted, it can be especially challenging to write a comprehensible introduction to a topic in mathematics, but the effort should be made to provide brief plain language definitions of specialized terms that appear unavoidably in the introduction.

Please take note of these:

"Minimize the use of jargon, and adequately explain its meaning when it is used....Do not introduce specialized words solely to teach them to the reader when more widely understood alternatives will do". (from MOS)

"Use a link when appropriate, but as far as possible do not force a reader to use that link to understand the sentence. The text needs to make sense to readers who cannot follow links. Users may print articles or read offline, and Wikipedia content may be encountered in republished form, often without links". (from MOS/Linking)

These recommendations should apply especially to introductory (lede) sections. DonFB (talk) 05:05, 8 January 2025 (UTC)

You and I stopped having the perspective of an average Wikipedia reader almost 20 years ago.

I think there is room in that advice to provide a generous number of links. The best approach provides both a good link and quick explanation. I don't think that, having provided a link, that we are absolved from needing to make the text understandable.

To go back to your Snowclone example, I don't love "It's a phrasal template" for the opening sentence, but I also don't love the fact that it's a phrasal template is no longer in the article. I'd suggest adding some of the "jargon" back into the lead, maybe in the form of a second paragraph that says something like "In linguistic terms, a snowclone is a phrasal template, which means it is a set pattern into which different words get substituted."

(Both patients and healthcare providers read Wikipedia. A favorite story: one Wikipedia editor who is a physician actually had a patient print out a Wikipedia article he had written. The patient brought the printout to him and demanded that their problem be treated exactly like the Wikipedia article indicated was the normal and evidence-based way to treat it, which obviously was how he would have done it anyway.) WhatamIdoing (talk) 06:54, 8 January 2025 (UTC)

I don't think the purpose of this page is a guide on how to make your article readable. It's title is "Readability tools" and an argument about whether they help editors meet our goals. Like the article it is largely sourced from, it needs to explain what the alternatives are, but those alternatives don't need to be comprehensive or perfect. Adding a wikilink can help readability if the user follows the link, learns the term, and comes back to finish the article. Going down the rabbit hole of following links on Wikipedia is also a well known thing and part of our "encyclopaedia" mission is to educate the reader in things they didn't expect to be educated in. But I agree if they have to go read another article in order to read this one, that adds friction to the experience. It may be necessary or unnecessary.

I prefer WAID's idea that we should look for opportunities to teach readers the jargon of the field, like hyperlipidemia or "phrasal template". Whether that jargon is in the lead depends on how important it is to the topic. I'd say an article on a treatment or test for hyperlipidemia, or a disease where that's a prime symptom, should probably include that word in the lead. But where this is a minor symptom or detail, it wouldn't be leadworthy. That "snowclone" is a "phrasal template" sounds leadworthy to me as it seems as linguistically relevant as the fact ball is a noun. I had not heard of snowclone or phrasal template but if you can teach me what both those are in the lead, you've done a great job. It isn't a big lead, and the article is on a linguistic feature, not about snow, so the linguistic terminology is pretty important. Colin°^Talk 11:37, 8 January 2025 (UTC)

"Ball" is a noun, but nowhere in the lede (or the full article) can that information be found. "If you can teach me" in an article, that's a good job, according your comment above. I want to point out something from What Wikipedia is Not. In the section Wikipedia is not a manual, guidebook, textbook, or scientific journal, item #6 states: "Textbooks and annotated texts: the purpose of Wikipedia is to summarize accepted knowledge, not to teach subject matter....examples intended to inform rather than to instruct, may be appropriate for inclusion in Wikipedia articles." I think this relates directly to the apparent motivation on the part of many editors to use excessive, needless or distracting jargon in the lede section of articles. They have expert or academic knowledge and reflexively add it in the form of jargon to the introduction of an article without considering who the readers may be. The result is an introduction that contains multiple "speed bumps" and poorly serves readers who just want, and deserve, a reasonably brief and uninterrupted summary of the subject. If they decide they want to be "educated" about the subject, they can dive into the full article. But I recoil at the idea: "if the user follows the link, learns the term, and comes back to finish the article." How about letting the reader stay on the page and get the basic information they came for instead of sending them elsewhere because Wikipedia is supposed to "teach" the reader?

On the matter of phrasal template: As I've said, I'm not opposed to technical language and jargon in the body of articles, and that phrase could be included there. Its original position in the first part of the first sentence was, not to put too fine a point on it, a clownish and fairly typical example of editing that shows no consideration for the general reader. My enduring principle is that such a mistaken practice should be corrected and discouraged. DonFB (talk) 22:55, 8 January 2025 (UTC)

An encyclopedia is inherently an educational project. We're not a textbook (e.g., with questions at the end of each chapter) or a how-to manual, but our goal is for people to learn things.

I don't think that people necessarily click on links much. I think they usually hover over them to get a quick definition/idea of what the word means. There's no "leaving and coming back" in that situation. WhatamIdoing (talk) 08:44, 9 January 2025 (UTC)

Yes, hovering, when using a mouse and desktop machine, is quicker than clicking to a new page. I believe a lot of people read on their phones, and tap-and-hold is quite a bit trickier to get a pop-up. Regardless, an intro section with half a dozen or more words of unexplained linked jargon or scientific lingo is, I argue, intimidating and off-putting by definition. Wikipedia policies, as I've noted, seem to discourage the idea the site is "educating" or "teaching" readers. I believe the paradigm is "informing". DonFB (talk) 05:15, 10 January 2025 (UTC)

I'm glad to see the addition of: "add both a link and also an explanation or brief definition". Consider appending something like: "Write the introduction in non-technical language with few, if any, unfamiliar linked terms of jargon." DonFB (talk) 00:53, 9 January 2025 (UTC)

Omitting "unfamiliar terms of jargon" will not always be appropriate for the introduction. We can't really say that "A diamond is a pretty rock", and there are a lot of people who won't know every word in the current lead (which begins: "Diamond is a solid form of the element carbon with its atoms arranged in a crystal structure called diamond cubic.")

I can see some room for simplifying this, but I can't see my way to removing every word that will be unfamiliar to some readers (e.g., element, crystal structure, even carbon, since this isn't the carbon footprint kind of carbon). The question for you: If an unfamiliar word really needs to be in the lead, do you want it to be linked or unlinked? WhatamIdoing (talk) 08:52, 9 January 2025 (UTC)

If an unfamiliar word is unavoidable in the lead, it should be linked. In many cases, however, an unfamiliar word or phrase in the lead can be replaced with a familiar word or phrase, which can be linked to the article for the unfamiliar term. I did that in one of my edits to Tidal locking, substituting "variability" for "libration" and linking it to libration. You can see what that article lead looked like as of June 25, 2019, before I worked on it (collaboratively). In other cases, the jargon can remain, but should be briefly defined or explained. Regarding Diamond: I think it's a reasonably good lead; I consider most of the words you specifically mentioned as familiar. Unfamiliar are: "diamond cubic", "metastable", "optical dispersion", and "refractive index". A bit less unfamiliar is "thermal conductivity", which could remain or be substituted by using a phrase like, "ability to conduct heat". The sentence about "diamond anvil cells" is unnecessary and should be put in the body instead. The other terms I've mentioned might remain, linked, but with brief plain English definitions/explanations. I believe "metastable" as it relates to diamond could be explained with a phrase about "unstable equilibrium" or even "very slightly unstable". "Optical dispersion" could be supplemented with phrasing about "light that is separated by individual colors as it passes through an object". "Refractive index" could be explained with a phrase like, "which determines how much the path of light passing through the object is bent".

Yes, these require more words, but the words are universally understandable to the vast majority of readers, certainly those who are native English speakers. These instantly recognizable words allow the reader to get through an introduction faster and with less frustration than seeing a couple of paragraphs littered with unexplained jargon, whether it's linked or not. If jargon is fully replaced, the substitute explanatory word or part of the substitute phrase can be linked to the technical term, as with "libration". I'm not against linking to technical terms/jargon if the link is from a familiar word or explanatory phrase. I am against the practice of linking unexplained jargon in the introduction as a substitute for communicating clearly with the reader. And, regarding the names of rocks farther down in the diamond intro: they are of course quite alien to most readers, but they're acceptable because they are explained as names of rocks, and I don't need to know their derivation to understand the sentence. DonFB (talk) 05:06, 10 January 2025 (UTC)