Wikipedia talk:Make technical articles understandable

See also: Wikipedia talk:Explain jargon

U.S. Government guide on plain language

This document is sometimes delightful. It's not exactly what we are trying to do here. Nor will everyone agree with everything in there. I don't want contractions creeping in, for one. But it's good stuff. I smiled when they made the comment about not being scared of having lots of periods. Some of the comments on paragraphs really resonated as well. See: [1].

Yes, they are too hard to understand. No, really

Here are some opinions about the comprehensibility of our articles:

• Wikipedia's science articles are elitist, 2017, Vice "Wikipedia articles about "hard science" (physics, biology, chemistry) topics are really mostly written for other scientists. This particular class of Wikipedia article tends to take the high-level form of a scientific paper. There's a brief intro (an abstract) that is kinda-sorta comprehensible, but then the article immediately degenerates into jargon and equations."
• Why are Wikipedia articles so difficult to understand?, Quora
• You're not smart enough to read Wikipedia, Popkin, 2012, NBC "Eleven years into its existence... Wikipedia has in some ways become more of a creative outlet for its contributing know-it-alls than a resource for the average human looking to lose his or her ignorance."
• Maybe Wikipedia readers shouldn't need science degrees to digest articles about basic topics, 2017, SlashDot
• WP:Don't be a smartypants

--Chetvorno^TALK 02:34, 15 December 2021 (UTC)

Yeah, well, see, I'm not all that impressed by the above criticisms. For example, the source in the third bullet (NBC News) dislikes the lead of our article on the sun ...

The Sun is the star at the center of the Solar System. It is almost perfectly spherical and consists of hot plasma interwoven with magnetic fields.[12][13] It has a diameter of about 1,392,684 km,[5] about 109 times that of Earth, and its mass (about 2×1030 kilograms, 330,000 times that of Earth) accounts for about 99.86% of the total mass of the Solar System.[14] Chemically, about three quarters of the Sun's mass consists of hydrogen, while the rest is mostly helium. The remainder (1.69%, which nonetheless equals 5,628 times the mass of Earth) consists of heavier elements, including oxygen, carbon, neon and iron, among others.[15]

... but praises Simple Wikipedia's counterpart:

The Sun is the star at the center of the Solar System. It is seen in the sky and gives light to the Earth. When the Sun is in the sky, it is day. When the Sun is not in the sky it is night. The planets, including Earth, go around it.

There certainly are people who don't understand that the sun is a star, or are unsure exactly what the solar system is. But I'm pretty sure that no more than a very, very small proportion haven't heard that Earth goes around the sun, and as for It is seen in the sky and gives light to the Earth. When the Sun is in the sky, it is day. When the Sun is not in the sky it is night -- just who are you informing? three-year-olds? I absolutely agree most of our science and tech articles could be made much more understandable to the layman, but really -- that's what you want us to shoot for? When the Sun is in the sky, it is day? EEng 00:41, 15 December 2021 (UTC)

I think you have too narrow a view of our readership. There are plenty of elementary age kids who read our articles. There are people with developmental deficits, immigrants from developing countries, and even ordinary people born in the US, who have little or no education. I would bet many don't know the Earth goes around the Sun. I dated a girl once whose father wouldn't let her go to school, you wouldn't believe her misconceptions. These are arguably the people who most need Wikipedia. It wouldn't have cost much to add several of the above sentences from Simple Wikipedia to our introduction (and if there was no demand for that level of info, why is there a Simple Wikipedia?). That might have been a better use for our introduction space than the sentence The remainder (1.69%, which nonetheless equals 5,628 times the mass of Earth) consists of heavier elements, including oxygen, carbon, neon and iron, among others. which could have been relegated to the article body.--Chetvorno^TALK 02:05, 15 December 2021 (UTC)

Even small children, people with developmental deficits, immigrants from developing countries, and ordinary people born in the US who have little or no education know that the sun is seen in the sky and gives light to the Earth. When the Sun is in the sky, it is day. When the Sun is not in the sky it is night. To answer your question, there's a Simple Wikipedia because someone thought it would be a good idea. And maybe it was, but for whatever reason it's almost completely moribund. EEng 06:23, 15 December 2021 (UTC)

Yeah, I think simple.wiki was doomed by an impossible mission. In theory, as I understand it, it was supposed to be able to cover everything en.wiki or other language Wikipedias did, in the same level of difficulty and detail, but just using simple language. The problem is that that's not actually possible. Or I suppose it's possible in theory, if you let the articles be 5x or 10x or 10,000x as long, but who's going to read them then?

The other possibility would have been to make it the Childcraft version of Wikipedia; that is, to explicitly cover only relatively simple material. I think that actually could be a worthwhile goal for the Wikimedia Foundation to pursue, if they wanted to direct resources that way. But it would be a very different thing from Wikipedia. The principles that have built Wikipedia wouldn't work at all for such an endeavor. --Trovatore (talk) 06:50, 15 December 2021 (UTC)

How do you propose to write an article "Bessel functions" such that a child, or a victim of a debilitating mental disability, or someone whose interests revolve around girls, alcohol, and baseball exclusively, understands it? There are people with issues out there, and there are children who are simply not ready to read about Bessel functions. That is NOT a good reason to cut off access to reference information for people who NEED that access. Someone in Africa, who uses Wikipedia to learn about radio wave propagation (Bessel functions happen there a lot!) should be able to read that article, without spending the money they don't have, on academic manuals, and without the article being vandalized by well meaning advocates of simplicity. Morycm (talk) 23:15, 4 February 2023 (UTC)

@Morycm: Bessel function is a good example of a Wikipedia article that could easily be made more understandable. Our jargon-laden introduction is almost totally incomprehensible to general readers:

"Bessel functions, first defined by the mathematician Daniel Bernoulli and then generalized by Friedrich Bessel, are canonical solutions y(x) of Bessel's differential equation

$$x^{2}{\frac {d^{2}y}{dx^{2}}}+x{\frac {dy}{dx}}+\left(x^{2}-\alpha ^{2}\right)y=0$$

for an arbitrary complex number $\alpha$, the order of the Bessel function. Although $\alpha$ and $-\alpha$ produce the same differential equation, it is conventional to define different Bessel functions for these two values in such a way that the Bessel functions are mostly smooth functions of $\alpha$.

The most important cases are when $\alpha$ is an integer or half-integer. Bessel functions for integer $\alpha$ are also known as cylinder functions or the cylindrical harmonics because they appear in the solution to Laplace's equation in cylindrical coordinates. Spherical Bessel functions with half-integer $\alpha$ are obtained when the Helmholtz equation is solved in spherical coordinates."

Here's a more understandable version, cribbed from Encyclopedia Britannica:

"A Bessel function, also called cylinder function, is any of a set of mathematical functions systematically derived around 1817 by the German astronomer Friedrich Wilhelm Bessel during an investigation of solutions of one of Kepler’s equations of planetary motion. Particular functions of the set had been formulated earlier by the Swiss mathematicians Daniel Bernoulli, who studied the oscillations of a chain suspended by one end, and Leonhard Euler, who analyzed the vibrations of a stretched membrane.

Scientists found that the functions appeared in mathematical descriptions of many physical phenomena, including the flow of heat or electricity in a solid cylinder, the propagation of electromagnetic waves along wires, the diffraction of light, the motions of fluids, and the deformations of elastic bodies. One of these investigators, Lord Rayleigh, also placed the Bessel functions in a larger context by showing that they arise in the solution of Laplace’s equation when the latter is formulated in cylindrical (rather than Cartesian or spherical) coordinates."

This is what most general readers of an encyclopedia want to know: what field it's in, what categories it belongs to, what properties it has, how it was discovered, what it's used for. Context is a good part of understanding. Unfortunately our technically specialized editors can't see the forest, only the trees. --Chetvorno^TALK 18:43, 6 February 2023 (UTC)

@Chetvorno: Your improvement would be great, if it did not eliminate the formula that defines Bessel functions. What if I read it specifically to find the formula, not read beginner-level musings about it? "You know, this is math. Like in school that you dropped out of. Don't bother your little head about it. Math is for those silly, stuck up people who think too much. You don't need to think and that's OK. You are strong and that's all that matters! You have the technology!" Morycm (talk) 01:57, 13 February 2023 (UTC)

Obviously, Bessel's equation could be added to the introduction. News flash: the introduction can have both technical information for technical readers and simple descriptions for general readers. It can serve both groups. --Chetvorno^TALK 21:41, 15 May 2023 (UTC)

Yeah, it doesn't really make sense to have a separate version for these readers, when this demographic could be served in our articles. I agree that in math that can be difficult, but for most STEM articles it doesn't require making the article 5x or 10x or 10,000x as long, just adding a paragraph or two to the introduction. But the fact that Simple Wikipedia was created shows that we're not doing a good job of that. --Chetvorno^TALK 19:27, 17 December 2021 (UTC)

Making articles more understandable does not necessarily mean that detailed technical content should be removed.

While some articles can be, in places, difficult to understand without a backing in the topic that they discuss, this often has more to do with the subject matter of the article, than it has to do with the word choice of its authors. In order to be factually robust, many articles must talk about things that could come off as complicated. In the past, Wikipedians have been known to insert tone tags into articles which contained language they found overly technical. If you are unsatisfied with the article's readability, a better solution would be to tag it as needing help from an expert-- somebody with a backing in the topic, who can re-write portions of it so that they're easier to read, without compromising their educational value. Generally, the tone tag is reserved for articles which fail to meet a basic standard-- articles that are poorly written, needlessly verbose or flowery, or which are clearly biased. As technical articles are typically created by professionals and tend to be of higher quality, the tone tag is not usually appropriate. I encourage Wikipedians who are interested in helping with this project to remove tone tags from articles which do not need them, so as to avoid confusing copyeditors. Many copyeditors will see the tone tag and look for something completely different. Atomic putty? Rien! (talk) (talk) 20:41, 21 June 2022 (UTC)

Exactly. The idea that people need knowlege pulped and chewed up is a misconception. If one understands everything in a Wikipedia article on a technical subject, that means they know the subject well. Then why bother reading this particular article? It's a waste of time. One of the first books I ever read was an encyclopedia of technology and science. Of course I did not understand, pretty much anything, but I got an overview of how much there is TO learn! Did it bother me? No, of course not. I think there are people who might be bothered by it, and the question is why. Did they get traumatized by someone who did not like answering questions? There are probably plenty such people, but hopefully, they will in time heal. It won't help them heal if we pretend that information is just not there to bother them. I doubt they are visiting technical articles just to feel bad. Morycm (talk) 23:02, 4 February 2023 (UTC)

@Atomic putty? Rien!: I don't think anyone's suggesting dumbing down articles or removing technical content. And an "expert needed" tag won't help, because it is the experts who write these incomprehensible articles. There's a difference between being an expert, and being an expert and a good encyclopedia editor. --Chetvorno^TALK 19:40, 6 February 2023 (UTC)

@Chetvorno Then I have an idea: use team approach. Get an expert, a writer, and a Wikipedia stylistic advocate. They will make sure it is technically correct, easy to understand, and reaches the widest possible audience for that subject. But if you expect to maximize audience, just do what top Youtube channels do: stick to sports, girls, beer, dogs, cats, and comedy. Because for those who look for information, a wikipedia that appeals to an average person from the global crowd would simply be a useless babble. Morycm (talk) 02:17, 13 February 2023 (UTC)

I agree with @Chetvorno 100%. Looking back, my opinion's definitely changed. When I wrote the earlier note, about a year ago, I felt strongly that accuracy shouldn't be compromised for readability-- but honestly, just like they said, a good encyclopedia editor can tone down the heavy detail, improve readability, and conserve accuracy.

Congrats to all parties for participating in the discussion. When in doubt, let's turn to our already-established best practices. I'm not sure why I felt the need to defend the conservation of detail so strongly before. Looking over the article, it does a really good job of keeping to the consensus with regard to detail and readability. ^-^ Atomic putty? Rien! 19:51, 13 February 2023 (UTC)

I also agree with Chetvorno. My particular concern is the lede paragraph of technical, or merely semi-technical articles. All too often Wikipedia writers leap instantly into textbook mode in the opening sentences, as if readers could understand arcane jargon, calculus or otherwise advanced mathematics. Such practice violates multiple policies and guidelines that article ledes should be written for the general reader and should not presume the reader is familiar with a technical subject. The "Bessel function" lede that Chetvorno showed is a very good example. When I do a Google search for something, I want a brief comprehensible summary of an unfamiliar word or concept. But frequently in Google results, I'm confronted with a blurb like Bessel function, and I will do exactly what Chetvorno did--I'll look for the Britannica version, because the Wikipedia introduction, though probably accurate, is nevertheless impenetrable, and therefore useless for my purpose. I also oppose the practice, in the lede, of linking jargon to separate articles. I added text to this Guideline to say that "Terminology in the lead section should be understandable on sight to general readers". Loading up a lede with linked terminology forces readers unfamiliar to stop and start multiple times as they hover or click on the terms, when all they wanted was an accessible summary of the topic which they could read uninterrupted. I don't object when editors include advanced technical material in the body of an article, but doing so in the lede violates policy and is a disservice to readers that should be avoided. DonFB (talk) 11:46, 14 February 2023 (UTC)

@DonFB: Thanks for the addition to the article. I have no objection to a lot of links in the lede, as long as it is not overly dependent on links: it should have brief explanations in ordinary language of the jargon used.

I absolutely agree with you about the confusing ledes in our technical articles. They are often ridiculously abstract and esoteric, when they are the part of the article that should be most widely understandable. I have rewritten dozens of ledes to be clearer. I think what happens is technically-minded people progressively expand the definition in the lede to be more abstract and cover more special cases, borderline cases and fields, until the definition becomes completely incomprehensible to ordinary readers. The ironic thing is that it is usually possible to incorporate the advanced stuff they want in the lede and still have it be adequately comprehensible to general readers, using ordinary good writing techniques. Most technically-educated Wikipedia editors are used to writing only for others in their specialty. Writing an encyclopedia requires a slightly different style of writing, but one which any educated person can do. Our editors just don't want to. --Chetvorno^TALK 21:01, 15 May 2023 (UTC)

I prefer to see no linked jargon in a lead, although I recognize that it is possible to show jargon with a useful parenthetical definition. However, I want to see such practice held to a bare minimum. It's also reasonable to link from an ordinary word which has special meaning in the context. An example is the link I made in the Tidal Locking lead from the word "variablity". Originally, "libration" appeared in the lead as a link with no parenthetical explanation, an example of exactly what not to do (link only from jargon, with no other help). Recently, I took a somewhat novel approach to making the case for rewriting a jargon-filled lead in the Femur article. The result was a successful revision with no objections and a small followup tweak by another editor. See the Talk topics beginning with Turgid Intro and the next two headings; note the (tl;dr) collapsed Virtual Discussion. DonFB (talk) 04:36, 19 May 2023 (UTC)

Music

It isn't just STEM (science, technology, engineering and mathematics) articles that are difficult for nonspecialists to understand. Some of the music articles about basic terms have frustrated comments on their talk pages. One example that I find difficult to understand is the first sentence of the Syncopation article. How many non-musically talented or trained readers can understand that sentence without studying it -- if at all? Kdammers (talk) 03:11, 12 September 2022 (UTC)

Further information template in the "Lead section"

This further information template now redirects to the article and not the section wanted. Maybe we could redirect it to Opening paragraph? Angerxiety 16:14, 7 December 2022 (UTC)