Wikipedia talk:Make technical articles understandable

See also: Wikipedia talk:Explain jargon

Should all articles be understandable?

The current scope of this guideline is to make technical articles understandable. I've been toying with the idea to write an proposed guideline about readability, to apply more broadly, but this would overlap with this guideline. Roughly 70% of the guideline already applies across the board. Non-technical articles (for instance about sport) may have jargon, and even articles without jargon can be made overly difficult when people use unnecessary academic language.

To do this, I would like reorganise and slightly expand the content related to reading level and readability, in a new section Choose the right reading level. A lot of this content is now collected under "Avoid overly technical language", where it doesn't fit well and has poor examples. In this section, I would like to give better examples of simple writing styles and link to copy-editing exercises such as WP:REDEX, which improve readability without compromising on content..

A possible new name for the guideline is 'Make articles understandable'. How does that sound? Happy to propose new text here if there is some interest. —Femke 🐦 (talk) 10:04, 4 January 2025 (UTC)

If I understand, you want to include a new section in this Guideline about readability, and also rename (not replace) this Guideline. Would your new Readability section replace the existing section "Avoid overly technical language", or would that section remain as is? DonFB (talk) 10:49, 4 January 2025 (UTC)

That's mostly right. I would like to split the section "Avoid overly technical language" into two. Keep the bullets points on jargon etc there, but move the bullet points on sentence lenght etc into the new readability section. —Femke 🐦 (talk) 10:56, 4 January 2025 (UTC)

Seems reasonable. I'm primarily concerned with the introductory or lead ("lede") section of articles. I have opined at length about the need to write the lede in plain English, with little or no jargon and few or no links to other articles. Too often, editors use jargon and links in the lede as a substitute for basic definitions or brief explanations. This practice derails readers looking for a readable summary of the subject. They're confronted with opaque terms or multiple links to the introduction of other articles, which themselves may be larded with jargon and links to yet more articles. The text in the body of many articles is indeed highly technical, but I'm not overly concerned about that. The introduction, however, may be the only part of an article seen by the majority of readers, most of whom are probably not experts in the subject. I think we, as an encyclopedia-writing community, are obligated to do our best to make the introduction comprehensible to anyone. DonFB (talk) 13:04, 4 January 2025 (UTC)

I strongly agree the lead is the most important bit to get right. I'm not mentioning it explicitly here, as I believe WP:explainlead is already clear on the topic. In terms of process, I believe there are two steps: 1) see if there is consensus on a readability section and 2) a possible RM to widen the scope of this guideline. —Femke 🐦 (talk) 14:40, 4 January 2025 (UTC)

I don't think a name/scope change/reorganization seems that useful, and am opposed to changing it without a better reason than this. Technical articles in particular have somewhat different needs and audiences than other types of articles. This page should not be interpreted to mean that "non-technical" articles should be unreadable, but specific advice about how to structure and pitch technical articles to make them useful to the full range of audiences isn't especially applicable to the typical Wikipedia article. –jacobolus (t) 07:51, 5 January 2025 (UTC)

Proposed readability section

Use the right reading level

Each reader has a different reading ability. Teenagers and non-native speakers may require plainly written texts, but even professionals prefer plain and clear text over complicated prose. Research shows that text on Wikipedia tends to be overly difficult. To make sure most interested readers can understand the article, use plain but formal English.

• Use short sentences and short paragraphs. Readers start to struggle when the average sentence is longer than 12 words. However, using too many short sentences in a row becomes dull and awkward; use a mix of sentence lengths to keep the reader engaged. Similarly, split long paragraphs into smaller ones.
• Write concisely and avoid redundancy. For instance, replace "The majority of critics gave the film negative reviews." with "Most critics gave the film negative reviews". These exercises help you recognize redunancy.
• Avoid overly difficult words. For instance, write "use" rather than "utilise", or "help" rather than "facilitate".

* Use active voice. For instance, replace "The cat was chased by the dog" with "the dog chased the cat".

• Eliminate long strings of adjectives, particularly technical adjectives.
• Use bullet points when appropriate.

Various online tools give an rough indication of the reading level. For instance, the Hemingway App estimates the US grade level of your text, while The first word has a more generic readability score and average sentence length.

References

This draws on text from the WP:MTAU#Audience and WP:MTAU#Avoid overly technical language. I've removed the bullet point about using more verbs, as I don't see how this helps understandability. I've added a bullet point on bullet points, conciseness and overly difficult (non-jargon) words. I'm not 100% happy with my proposed section title, so keen to hear others. —Femke 🐦 (talk) 14:40, 4 January 2025 (UTC)

OK, so this isn't my only or maybe even most important thought, but my eye was grabbed by the bit about active voice. It may be worth mentioning that, other things being equal, active voice is more easily understood than passive voice. But there are editors who take it as some sort of rule that passive voice should always be converted to active, which is not true; when the grammatical object of the verb is significantly more relevant than the grammatical subject, other things are not equal, and it's often a good idea to use passive voice rather than introduce an unimportant verb subject.

I would be OK with it if it's clarified that it's a point to consider, but that passive voice is often useful and should not be blindly converted to active. --Trovatore (talk) 21:10, 4 January 2025 (UTC)

I don't think this is specific to technical articles, and therefore I think it should be proposed for one of the Wikipedia:Manual of Style pages. (I think we need a page that is specific to technical articles, regardless of whether we also have one for (e.g.) pop culture or business articles.)

Overall, I suggest that you read https://www.uxmatters.com/mt/archives/2019/07/readability-formulas-7-reasons-to-avoid-them-and-what-to-do-instead.php and maybe think about why FACs are supposed to have "brilliant prose" instead of "short sentences". WhatamIdoing (talk) 01:21, 5 January 2025 (UTC)

Because you mentioned the Hemingway app (which I find valuable when simplifying text for translation), I have written Wikipedia:Readability tools. To give you an idea of how (un)helpful they are if you don't know what you're doing and how to react to the results, note that the single word Wikipedia scores everything from Kindergarten level all the way up through post-graduate. WhatamIdoing (talk) 05:36, 5 January 2025 (UTC)

In terms of passive voice, can you think of a concise way to make this clear?

Regarding the tools: I've added the word rough to the proposed text. The way I rewrote the advice (Hemingway is already mentioned), was to stress it just gives an impression of reading level. I believe they work well as a "wake-up" tool, and that simplifying text is usually best done without the tools.

Compared to the current guideline, I've weakened the statement about sentence length. Sentence length is almost always mentioned in readability guidelines elsewhere. I don't think text can be engaging if average sentence lenght is too high, at least not to a wide audience. I don't see a trade-off there between the FAC criteria and the need for readability. —Femke 🐦 (talk) 08:44, 5 January 2025 (UTC)

On the passive, I’m not sure how simple you can make it. An encyclopaedia is one place that the passive voice should be more common than it is elsewhere, and I frequently find myself changing a sentence to the passive to help readability. The best way I find to think about it is to consider an article about a person (“Joe Smith invented the foo process in 1991…”) compared to an article about a passive thing (“The foo process was invented by Joe Smith…”). But in an extended passage, it may work better to switch: “By 1987, Smith’s bar process had begun to prove inefficient at scale, and he began work on an alternative. Working with help from Jones again, Smith formulated the foo process using a salt bath instead of…”. Really the editor just has to use judgement, and I wouldn’t want to encourage one way or another as a rule. — HTGS (talk) 10:30, 5 January 2025 (UTC)

I've removed it. In practice, I rarely switch voice when I rewrite a Wikipedia article to be understandable. In academic writing, this comes up a lot (people using stilted passive voice to sound more formal), but perhaps less so here? If we go for the more difficult route of a separate guideline, we can put examples where switching from either passive or active makes the sentence easier. —Femke 🐦 (talk) 11:12, 5 January 2025 (UTC)

Where should the readability content be

(splitting the "where" discussion from the "what")

This seems somewhat off topic and out of scope for this page. Maybe propose adding such advice at some other page? –jacobolus (t) 07:54, 5 January 2025 (UTC)

@Jacobolus: What other page do you think the current/expanded guidance can be moved to? WP:ACCESSIBILITY might make some sense, but would be more surprising than keeping it here, as people rarely connect readability to specific disabilities.

@WhatamIdoing: the reason I'm proposing we create one guideline for understandability is that there is not a clear separation between making technical articles clear, and making articles understandable in general. For instance, adding examples is useful even for less technical articles. Most of the guideline will naturally be about technical articles, as that's where we're failing most with regard to understandability. If you want to explain difficult concepts, readability is one tool in your toolbox.

From a more practical POV: I think the alternative is to develop an entire new (MOS) page, and try to get consensus for that. I imagine that would be much more difficult than doing a reorganisation and minor expansion on the current readability text in this guideline, even if we decide not to rename the page. I furthermore don't want us to get more P&Gs; it's already tough to become familiar with the current ones. —Femke 🐦 (talk) 08:46, 5 January 2025 (UTC)

I think your proposal substantially misses the purpose of this current page: giving advice specifically to editors of technical articles about how to make those articles broadly accessible, along with some discussion about why that is important, which also serves as an easy place to point editors when this topic comes up in talk page conversations. I don't think your proposed changes would be particularly helpful at supporting that purpose, and might even harm it via distraction and loss of focus. Personally I don't think recommendations to use the easiest-to-read possible prose are appropriate as a site-wide recommendation for a general encyclopedia, or at least not without extensive discussion of context and qualification, but in any event I don't think they belong here. –jacobolus (t) 10:49, 5 January 2025 (UTC)

To me, this guideline will be more focussed after the reorganisation, as more general readability advice is separated from the more concrete advice around technical articles. At the moment, it's mixed.

I'm not saying we should use the "easiest-to-read" prose. Readability is a function of expected audience, and just like with technical difficulty, should use WP:ONEDOWN to get the level right. Which again shows the two are heavily interlinked. —Femke 🐦 (talk) 11:08, 5 January 2025 (UTC)

Adding more material to the page which is not focused on making technical articles understandable will make it less focused, regardless of how the sections are organized. I tend to agree with jacobolus here; as far as I can tell, it seems like your proposal would make this page less useful for the purpose it currently serves. XOR'easter (talk) 18:46, 6 January 2025 (UTC)

Wikipedia:Writing better articles is a possibility for general advice. WhatamIdoing (talk) 07:09, 6 January 2025 (UTC)

Hah, that's quite an eclectic explanatory essay, with some sections already related to readability. I've often cited parts of the page, but never really registered it's all on one page. A readability section would fit. The key disadvantage of putting it there is that topics related to understandability (conciseness, know your audience) are interspersed with other topics, which means it works less as a didactic tool compared to a more focussed placement here. —Femke 🐦 (talk) 13:33, 6 January 2025 (UTC)

Most of our help pages would benefit from re-organizing and de-duplication. WhatamIdoing (talk) 18:48, 6 January 2025 (UTC)

Very much so. Our articles can be pretty bad about this, but our documentation is worse. XOR'easter (talk) 18:52, 6 January 2025 (UTC)

Readability score pseudo-science

Can we please put this American readability grade-score pseudo-science to bed. I see above that WAID has written Wikipedia:Readability tools which is inspired from discussions I've had with them over the years, and in particular the excellent article Readability Formulas: 7 Reasons to Avoid Them and What to Do Instead. In short, the scores themselves are bunk and the advice such websites offer is also bunk. Readability isn't something you can measure with a simple tool and score with a grade. The tools encourage mindless editing that produces short choppy sentences and eliminates important terms and facts.

The readability of text can only be measured by involving a human brain. Ask a friend to read your text out loud. What do they stumble on. Ask them which bits they found hard to understand. Did they find it engaging enough that they want to read the rest of the article, or so off-putting that they made excuses to go? Improving the readability of prose is more than word length and sentence length. Having the first clue about the subject one is trying to explain is, in my view, a tad more important. Introducing concepts the reader must learn and avoiding jargon they don't need. Organising it into sections and paragraphs and illustrating it with diagrams and pictures. These tools help not one bit with the important aspects of brilliant prose.

As a test, I took the NHS Website pages for a complicated condition: https://www.nhs.uk/conditions/tuberous-sclerosis/. The NHS pages are aimed to be highly accessible and highly regarded for such. Let's look at the opening sentence and how one of our student editors, who have been asked to use Hemingway to improve it, might get on.

Lead

Tuberous sclerosis, also known as tuberous sclerosis complex, is a rare genetic condition that causes mainly non-cancerous (benign) tumours to develop in different parts of the body.

Hemingway tells me this is "very hard to read" and colours it angry red. It's like a computer game. I'm encouraged to turn this text background white. It suggests This sentence is too long and complex. Use shorter sentences and simpler words. This is a defining sentence, giving the reader the name of the condition and a very brief description about what TSC is. The literature uses two names for the condition: the full name tuberous sclerosis complex, and the original shorter name of tuberous sclerosis. Our student takes the scissors to the parenthetical to make two sentences.

Tuberous sclerosis is a rare genetic condition that causes mainly non-cancerous (benign) tumours to develop in different parts of the body. Tuberous sclerosis is also known as tuberous sclerosis complex.

Hemingway tells me the first sentence is still "very hard to read", with the same problem (length) and solution (chop chop). Let's split the sentence in two.

Tuberous sclerosis is a rare genetic condition. It causes mainly non-cancerous (benign) tumours to develop in different parts of the body. Tuberous sclerosis is also known as tuberous sclerosis complex.

Hemingway tells me the second sentence is still "hard to read". We explained to the reader that non-cancerous tumours are termed "benign tumours" by professionals. We could eliminate that bit of technical language.

Tuberous sclerosis is a rare genetic condition. It causes mainly non-cancerous tumours to develop in different parts of the body. Tuberous sclerosis is also known as tuberous sclerosis complex.

Now Hemingway isn't happy about "mainly". It says that's an adverb and I should use a forceful verb instead. Our student editor can't figure out how to forcefully "cause mainly" so just removes the word.

Tuberous sclerosis is a rare genetic condition. It causes non-cancerous tumours to develop in different parts of the body. Tuberous sclerosis is also known as tuberous sclerosis complex.

Hemingway is happy with the outcome. I am not. We now have a very clunky trailing sentence that verbosely covers an AKA. The lead sentence is no longer a defining sentence. The "that" in the original is key. That the disease is rare or genetic doesn't define it at all: lots of conditions are those. We've sacrificed the moment to teach the reader that non-cancerous tumours are called benign tumours, which is something they'll need to know for this topic. And we've lost the piece of information that sometimes the tumours it causes aren't non-cancerous, though that is rare. The lead paragraph is now choppy and has all the engagement of random bullet points on a PowerPoint slide. One of our brilliant-prose editors could perhaps rewrite that lead sentence in a way that reads brilliantly and mostly satisfies Hemingway. But doing that requires talent, writing experience, and a deep knowledge of the subject so you don't screw up. None of which Hemingway thinks necessary.

A random symptom

Another example:

Abnormal growths or patches of skin do not usually present a serious health problem, but their appearance can affect a person's confidence and self-esteem..

This is also highlighted as being "very hard to read". If I chop it in two

Abnormal growths or patches of skin do not usually present a serious health problem. Their appearance can affect a person's confidence and self-esteem.

it is now magically perfect. That little chop transformed it from being "very hard to read" to "easy to read". Really? But the original contained an important balance between two kinds of health issue, physical and mental, which is now lost. And now the second sentence misleadingly appears to be making a general point about a person's appearance, rather than the appearance of abnormal growths or patches of skin.

Other issues are mindless simpler word choice suggestions. "however" is replaced with "but", which is indeed simpler, but (see what I did there) not often appropriate. A sentence on children who may "benefit from" attending a special school suggested instead they should "enjoy" attending a special school. The word "monitor", meaning ongoing repeat examination, is replaced with "check" which does not.

Research pesudoscience

The text proposed in the section above said "Research shows that text on Wikipedia tends to be overly difficult." That so-called research did not ask people to read our articles and then take a comprehension test on how well they understood it. Instead they used seven different formulaic readability tools. Why choose seven? That's like asking seven people to look at a tall building and tell you its volume in square metres. They'd all be hopeless at it. The source claims the Coleman–Liau Index says "the text was too hard for most readers and only appropriate for 11th grade and above." The Flesch-Kincaid Grade Level said "the text was challenging and could only be read by professional readers" On the LIX scale "all pages were extremely difficult to read and required a college-level education". But the LIX scale is

• LIX = wordLength + sentenceLength

where:

• wordLength = percent of words of more than six letters
• sentenceLength = average number of words per sentence

You know, during Covid-19 we all laughed when some eejit suggested ingesting bleach as a cure. Working out whether an article on a novel disease requires the reader to have a "college-level education" or be a healthcare "professional" based on that kind of simplistic pseudo-science is laughable too.

What a bummer that coronavirus has more that six letters. If we'd had a flu pandemic, we could all pat our selves on the back for writing super-readable articles. -- Colin°^Talk 18:51, 5 January 2025 (UTC)

Yes, this is a problem. You really shouldn't use these tools that way. If you understand a given tool, then you might be able to get some value out of it. (For example, the Hemingwayapp reminds me to omit needless adverbs.) But "just try to make the computer happy" is a path to bad writing. WhatamIdoing (talk) 06:54, 6 January 2025 (UTC)

I agree. Don't write for the machine. XOR'easter (talk) 18:41, 6 January 2025 (UTC)

I've seen people misuse these readability tools like this before on articles. These tools were not made to analyse individual sentences, and if you use them like that, you get choppy text as you argue; The full NHS page you mention scores well. Calling this pseudoscience feels like OR to me however. You create indices, you validate them (e.g. [1]), and in the next step you use them as is. In medicine, this is how loads of questionaires are designed.

I would love us to emulate the NHS more in this sense. Two of their guideline documents for writing plainly:

• How we write, which roughly corresponds to the advice I suggest we add somewhere in the previous section. Use simple wording (not only avoiding jargon), use bullet points, be concise.
• Health literacy ‘how to’ guide (page 17), with similar advice.

Curiously, both documents do point to different readability indices, the second one with appropriate caveats.

Do you disagree with the conclusion that Wikipedia's (technical) content is too difficult in general? Even in my own fields (maths, climate, energy), I struggle to read many of our articles. —Femke 🐦 (talk) 19:27, 6 January 2025 (UTC)

I have also struggled with reading articles here in my own field. The article that David Eppstein, JayBeeEll, Russ Woodroofe, and I recently coauthored [2] discusses the problem. I am unsure of how to make progress on it to any meaningful extent, other than recruiting more editors who know technical subject matter and care about writing clearly. We could perhaps also do better at prioritizing our efforts and improving the reading experience of the most central/frequently visited articles in technical fields. XOR'easter (talk) 20:17, 6 January 2025 (UTC)

Even though I work hard to write clearly, what I write often uses sentence structures and words that are longer than they need to be. When I notice this, I edit my text to use simpler words and simpler grammar. Tools such as the ones described here can provide helpful reminders to do this. I agree that following their recommendations mechanically can lead to mechanical and uninformative prose, but they can still be useful if used with care. —David Eppstein (talk) 21:27, 6 January 2025 (UTC)

I don't think our articles are too hard to read because editors can't find resources about how to write more clearly. Indeed, such resources (both on- and especially off-wiki) abound and are easy to locate by web search or just asking. Our articles are hard to read because (a) the material is often complex and difficult, (b) writing clearly for every possible audience from schoolchildren to professionals is damn hard, and (c) Wikipedia doesn't have enough volunteer author–editors who are both subject experts and excellent writers with the time to devote significant attention to each technical article. –jacobolus (t) 21:20, 6 January 2025 (UTC)

I don't struggle to read our articles about medical topics. I frequently find that they are not well written, but not difficult to understand. I think one of our problems is that we don't Wikipedia:Use our own words enough. I think we often mimic the style of the sources we're citing, which are often journal articles and therefore not using an writing style that is appropriate for an encyclopedia. WhatamIdoing (talk) 00:39, 7 January 2025 (UTC)

Kudos to authors of articles about medical topics who have managed to make them accessible. My impression is that there are more technical barriers (more complicated and more abstract pre-requisite knowledge that takes more effort for learners to make sense of) in mathematics or extremely mathematical subjects than there is in most other fields. I agree that quite a lot of the problem is too terse and spare a style, and we can certainly do better; I'm all in favor of people trying to make highly technical articles more accessible. But it takes a lot of effort and care. If it were easy, it would already have been done. I don't think pointing people at hemingwayapp or urging them to use short sentences and avoid the passive voice is going to help much. –jacobolus (t) 01:20, 7 January 2025 (UTC)

I'm not sure that we've made our medical articles more accessible. I can only say that I personally don't find them incomprehensible.

I do think that mathematics has a bigger challenge, because it's more specialized. WP:ONEDOWN is easy for medical subjects. In fact, most parts of an article about a disease could be made understandable to 10 year olds. But I'm not sure that most advanced math articles could be explained that simply. At a certain point, you have to be able to think abstractly to understand the math. WhatamIdoing (talk) 02:26, 7 January 2025 (UTC)

If you asked someone what the "readability" of a text is, they might say it is whether the text is comprehensible, interesting, or enjoyable. The NHS page says Being mathematically based, readability tests are unable to determine the likelihood that the document is comprehensible, interesting, or enjoyable. It’s possible to obtain good readability scores with gobbledygook, providing the content contains short sentences made up of monosyllabic words. These readability tools (like Hemingway) are promoted as a tool to help you improve the readability your text, which is pseudo-science. Imagine instead they were promoted as a tool to identify and write self-help books that really changed your life, or instruction manuals that really helped fix your washing machine or romance novels that melted your heart. You'd look at this "how many words have more than six letters" logic from the 1950s and scoff. So why would anyone think they'd help identify and encourage encyclopaedic articles that fill your brain with knowledge?

A guideline called "Make technical articles understandable" has no business linking to them to achieve that purpose. I accept that if someone wants to use such an automated tool, as a first rough sweep at which Wikipedia articles might be hard to understand, I don't have a problem with that. They'll miss a lot that are hard to understand because the writer didn't understand themselves. And they'll unfairly target subjects with longer names than those with short names. But any tool that thinks "playground" and "elephant" are difficult words because they have more than six letters, has no comprehension whatsoever of what really makes a difficult word. The grade score is a crude measure like assuming a child that is taller than another is older, or that a meal that costs £30 will taste better than one that costs £3. But you can't make someone older by making them stand on a box and you can't make your McDonalds taste better by putting a £20 note in the bun. And yet we have student assignments asking classes to use Hemingway to make our articles better. And all they do is chop sentences and remove the words we're trying to teach. The initial way to help our readers understand a topic is for the editor to first understand it well and read a variety of sources of different levels. Then you stand a chance of explaining it to the general reader. -- Colin°^Talk 14:47, 7 January 2025 (UTC)

Wrt the NHS, I agree they do a great job at making their pages accessible. But they have a very different purpose than our good or featured articles. Their primary mission is to help you quickly understand if you need to contact the medical services, or what you can do for yourself. They aren't "encyclopaedic". They write about and give advice for "you" all the time. They aren't afraid to lower themselves to talking about poo and farts if it gets the message. Most of their pages are very short and the reader is only expected to spend a short time on them. So you can get away with short sentences and loads of bullet points. It is much closer to a PowerPoint than a booklet. -- Colin°^Talk 15:02, 7 January 2025 (UTC)

I think our technical articles desperately need clarifying, but I can't see the readability tools making much difference. I agree with most of the arguments against them above. In addition, the position of most of the offending expert editors is that they can't simplify; the jargon and multisyllabic words that make the text opaque have to be in the introduction, or it is bogus. So they will refuse to use the readability tools. Also as mentioned above, many editors are savvy enough to game the tools, write an incomprehensible intro that still passes, and then say "My intro has a low score, end of discussion." --Chetvorno^TALK 03:58, 10 January 2025 (UTC)

Hemingway

Inspired by the above discussion of the Hemingway app, I gave chatGPT the prompt Rewrite Wikipedia's article on "tuberous sclerosis" in the style of Ernest Hemingway.. I thought y'all might be interested in the results. --Trovatore (talk) 23:46, 6 January 2025 (UTC)

Extended content

There was a disease, a quiet disease. It did not scream, it did not cry out for attention. But it was there, under the skin, in the mind, in the heart of the body. Tuberous sclerosis. A name like a slow, steady wind blowing across a wide, flat plain.

The body, it carried the weight of it. The skin would show bumps, lumps, strange growths. Nodules, cysts. They were benign, they were harmless in a way, but they were there. Inside the brain, they made the person struggle. Seizures, shaking hands, eyes that did not see right. There were no tears, no easy words. Just the work of living, and the fight to keep going.

It didn’t always show itself when a person was born. Sometimes it came early, like a storm on the horizon, but sometimes it stayed hidden for years. It was in the genes, the DNA that made you, passed down from father to son, from mother to daughter. You could inherit it, and not know it, until you saw the marks on your skin or you saw the fight in your eyes.

Doctors knew of it, but there was no cure. They could manage the pain, the shaking, the confusion. They could help with medicine, maybe surgery, to cut out the parts of you that had gone wrong. But it was a constant. It did not go away, and it did not rest. It lived with you, like a shadow.

The world did not stop for it. You did not stop. You kept moving, walking the road. Life was still there, hard and full, despite the disease. That was the way it was. The fight for life, for what you could hold, was constant. Even when you fought against the unknown. Even when the shadows seemed longer than the light.

Tuberous sclerosis was no more than that: part of the struggle. The struggle to live. To hold on.

Great stuff. Bot could nominate itself for a Pulitzer. DonFB (talk) 00:18, 7 January 2025 (UTC)

Hemingway's modus operandi was to show only the surface and omit most of the story, leaving readers to puzzle it out for themselves. I'm not sure Wikipedia should have similar goals. [Edit: I was also amused at the result.] –jacobolus (t) 02:13, 7 January 2025 (UTC)

Yeah, that was similar to what I was thinking when I tried this experiment. Of course just because the app is called "Hemingway" doesn't imply that it really wants you to write like Hemingway. It's not a serious contribution to the discussion, just a lark.

By the way, you might notice that the text doesn't have much to do with our article on tuberous sclerosis. I don't think it really looked at the WP article at all. I tried "Rewrite Wikipedia's article on determinacy in the style of Robert Heinlein", and it gave me something that was clearly about determinism, not determinacy. --Trovatore (talk) 02:28, 7 January 2025 (UTC)

Edited "audience" section

The last sentence of the last paragraph of the "audience" section said [t]he article should be written in simple English that non-experts can understand properly.. While this is good advice in general, in context it was contradictory to the main burden of the paragraph in which it occurred, which was explaining the situations in which it may not be possible to write the article in such a way that non-experts can understand it. --Trovatore (talk) 19:06, 20 March 2025 (UTC) Further info: The sentence appears to have been added first in this edit in 2019, then later copyedited. --Trovatore (talk) 19:23, 20 March 2025 (UTC)

Improving the structure of this guideline

When I suggested adding this guideline to the WP:featured article criteria, Gog the Mild objected partially because of the quality of the guideline. One thing that stands out to me is that the structure of the guideline is poor. We've got most of our content in the random 'Rules of thumb' section, rather than structured in appropriate sections. That means that WP:ONEDOWN is divorced from the audience section (can be taken out of context), that WP:OVERSIMPLIFY is divorced WP:TECHNICAL. Ironically, providing a good structure is one of the key elements to understandable writing.

So I'd like to propose a new structure based on a few books I've been reading on the topic In terms of steps, I propose we first agree on a proper structure. Once we have an agreed outline, I'm happy to draft each section, and bring it here for refinement and consensus.

Proposed new structure

I'm currently thinking of the following structure:

1. Know your audience (less waffly as before, with a sentence about the curse of knowledge, when to keep technical detail, 'introduction to' articles)
2. Use clear and plain language (about cognitive load, being concrete, avoiding jargon where possible)
3. Structure articles well (explainlead, give a good structure, putting easier bits on top of sections)
4. Explain new concepts (about whether an article needs a background section, what to call it, using examples and comparisons etc)
5. Use of visuals (going more deeply into how to design visuals, for instance, keeping graphs simple, not using unnecessary jargon in graphs etc).
6. Reviewing (encouraging people to ask their friends and family for help, using the GA process or Wikiprojects to double check if the article is understandable).

There will be quite a few new things in the new structure, but my current thinking is that I'd like to preserve all the existing guideline shortcuts.

References

—Femke 🐦 (talk) 11:46, 3 August 2025 (UTC)

While I haven't yet looked at the detail of the structure you're proposing, I would very much be in favour of a concerted community effort to improve this guideline. Your structure seems a good place to start. MichaelMaggs (talk) 10:20, 5 August 2025 (UTC)

Pinging those who've been active here in the last 12 months: @Trovatore, Jacobolus, Chetvorno, Colin, WhatamIdoing, David Eppstein, HTGS, DonFB, Toadspike, and Tito Omburo:. —Femke 🐦 (talk) 07:30, 5 August 2025 (UTC)

just wanted to poke my head in here and say, regardless of how the guideline ends up looking, you're likely to have added quite a lot of utility for your fellow editors. much appreciated! Remsense 🌈 论 07:36, 5 August 2025 (UTC)

I'm a little maxed out in real life to focus much on this. I think this sort of advice guideline is more likely to benefit from an overhaul than others. Cruft accumulates and the structure fossilises. Might be good to work on a draft page rather than the guideline instead in case one's enthusiasm leads to blanket reverts. I suggest also looking through the talk history for which sentences or wisdom was hard won and thus likely to be needed to be kept. Once you are done with this, there's a bloaty guideline called WP:MEDRS that could do with a haircut. -- Colin°^Talk 10:24, 5 August 2025 (UTC)

I agree with that procedure. Given the quite strong views expressed in the discussions above about the appropriate level for the leads of maths and physics articles, editing collaboratively on a separate workshop page might be more likely to produce lasting results than bold changes to the current guidelines. MichaelMaggs (talk) 10:33, 5 August 2025 (UTC)

This structure looks great. I really appreciate your work on this, as our guidelines tend to ossify, often to the detriment of the project. The current structure is incredibly messy. Toadspike [Talk] 16:23, 6 August 2025 (UTC)

Ditto what Colin and Remsense said, except that if you can get away with some move-big-chunks-around edits first, without objection, on the actual page rather than before you start a draft then that will likely put you ahead. I did kinda the same for MOS:LAW in the past, and reworking this stuff is 100-fold easier without people watching over your shoulder questioning and nagging every decision you make. That’s part of the ossification process though, no doubt. And I had no idea Pinker had a style book—is it good? — HTGS (talk) 00:29, 7 August 2025 (UTC)

I'll make sure to reread the historical discussions. One way I hope to resolve some of the tensions between those who want articles to be more geared towards a general reader, and those who want it more 'useful' towards more experienced readers, is to add content on how to make articles understandable for those with more background knowledge. I've only read the chapter on understandability from Pinker, and it's really good, giving concrete tips backed up by science. Guidelines usually don't have citations, but in this guideline when I omit a citation, people usually revert asking for evidence e.g. today. Would it make sense to keep a few citations in for material likely to be challenged? —Femke 🐦 (talk) 06:11, 7 August 2025 (UTC)

Support -- it would be a different sort of article than now, more of a full guide than a collection of tips, but I think that would be significantly better and more useful. It might be useful to add the new sections one-by-one for getting through consensus, but I don't have much experience with this so I don't know. In any case, mark me as support if it matters. Mrfoogles (talk) 18:40, 7 August 2025 (UTC)

Lovely to see support for the new structure. Based on all of this:

• I'll be making some changes directly to the guideline to get this new structure in place, as far as it's possible with the existing content. We'll see if it sticks.
• I've created WP:make technical articles understandable/Workshop to rewrite from scratch. My strategy is to first add things that are missing or incomplete from the current guideline, and then add in the bits of the existing guideline that are well written. Help welcome.
• Once that is done, people can see the overall proposed change in context, while we try to find consensus section-by-section.

This guideline used to be part of the manual of style, and I'd like to get that feel back by providing a lot of examples. Will probably need help to get more examples from areas like law and psychology. My mind is also drawing blanks on how to write the visuals section for such a wide range of subjects. If people are aware of good examples to show in that section, I'm all ears. —Femke 🐦 (talk) 19:45, 7 August 2025 (UTC)

First draft ready for comment

First draft is ready for comment: Wikipedia:Make technical articles understandable/Workshop (compare ). Summary of changes:

• Add content on plain writing
• Add content on collaboration as a means of writing understandably
• More of a focus on writing understandable for all: experts also benefit from being able to learn things rapidly.
• Added examples throughout. Do they work? Are there better examples?

—Femke 🐦 (talk) 07:46, 13 August 2025 (UTC)

Pinging additional folks for feedback (active between 1 and 2 years ago on this talk): @Dhtwiki, SMcCandlish, Piotrus, The Transhumanist, and Siroxo: —Femke 🐦 (talk) 11:03, 17 August 2025 (UTC)

Audience

Overall I prefer the top portion of the existing § Audience section, and the changes seem somewhat arbitrary. The main change as I read it is to make the narrative choppier. (Edit: Hopefully it doesn't seem like I'm just being contrary or obstructive. My comments aren't intended that way.)

• The change from "graded" to "classified" seems fine, or maybe we can find an even better way to phrase this.
• The change from "varied audience" to "highly varied audience" seems unnecessary. The intensifier is vague/undefined, and doesn't add anything.
• After the bare mention of readability throwing in "Various free online tools" is distracting; this should be placed somewhere later on the page if included at all.
• I'm not convinced about putting the survey here – it seems distracting – but survey data should be presented carefully. The proposed text, "In general on Wikipedia, around 40% of readers say they are unfamiliar with the topic they are reading. Around 25% of readers are looking for in-depth knowledge, while others may be interested in a fact or an overview of the topic.", can't be meaningfully interpreted without knowing more about the survey methodology. More accurate would be something like "In a voluntary survey in June 2019 of a random sample of adult English Wikipedia readers, recruited from whichever article they happened to have arrived at, about 40% of respondents said they were not previously familiar with the topic of the article. Responses were roughly evenly split between three choices of motivation – looking up a specific fact, getting an overview of the topic, or getting an in-depth understanding – with almost 40% of readers looking for an overview." It's important to be explicit because there are several serious biases with this kind of survey, most obviously selection bias in the voluntary response, but also a random sample of page views will give a radically different result than a sample taken at a random time. (For instance, I spend most of my time while reading scholarly journal papers reading carefully in depth, but if you pick randomly from papers I have ever looked at, for the vast majority I was just skimming the abstract to figure out as quickly as possible that I could ignore the paper. I hope for paper authors to make their abstracts describe the topic of their work as clearly and concisely as possible so I can leave, but I want them to include full technical details in the body of the article so I don't waste my time scratching my head about a vague handwave.)
• The existing text, "On the other hand, many subjects studied at an academically advanced level remain of interest to a wider audience. For example, the Sun is of interest to more than just astronomers, and Alzheimer's disease will interest more than just physicians.", reads more smoothly than the proposed alternative, "Other advanced topics, like the Sun or Alzheimer’s disease, remain of broad public interest, and should be written with this audience in mind." The proposed text is also confusing (readers have to figure out that "this audience" implicitly refers to "the broad public").
• The existing text, "Some topics are intrinsically complex or require much prior knowledge gained through specialized education or training. It is unreasonable to expect a comprehensive article on such subjects to be understandable to all readers. The effort should still be made to make the article as understandable to as many as possible, with particular emphasis on the lead section." seems more focused and clearer than the proposed "Some topics naturally draw a narrower audience, for example those requiring years of specialist study in advanced mathematics, specialist law, or industrial engineering. These audiences benefit from clear explanations, effective visuals, and plain English, but need less background detail or definitions of jargon." Emphasizing the intrinsic complexity of some topics is helpful.

I have to go for now, but I'll try to review more later. –jacobolus (t) 17:00, 13 August 2025 (UTC)

Thanks for the feedback! At this point, this detailed constructive feedback is really useful. The main gripe I have with the old text is the verbosity and longwinded sentences. I know I often err in the other direction. There were a few issues issues I had with the content, like implying that only knowledgeable people would read a full FA, and the subtly condensending language towards less knowledgeable readers ('look at pictures'). I've now written an option B (yet to rewrite option A), which tackles only these issues without trying to condense the text itself. What do you think?

• Changed classified to grouped, which I think works better than either graded or classified (both too formal).
• Removed highly.
• I'm not married to including the survey, but I do think it provides one of the few data points we have on how people use Wikipedia. I'm image if there is a bias here, it might bias towards people who are looking for more in-depth information as they have more time to notice the banner? We might be able to include those details in a footnote. It would distract in the text. One of my long-standing ideas is to bring back reader feedback for article writers who sign up to actually get data specific to their article on what content people are looking for and if they find the explanations clear. You make a good point about the time spent on articles vs number of articles visited, and I'm going to mull this over a bit. I could keep move the English as a second language bit into the bullet points.
• Of those two old sentences around Alzheimer's, I like the second, but have to plough through the first. Have reworded it more concisely in the new option B. —Femke 🐦 (talk) 19:28, 13 August 2025 (UTC)

"Longwinded sentences", meaning prose that flows together and can be read straight through, is much better than (to exaggerate a bit) a staccato chop of disconnected non sequiturs. –jacobolus (t) 19:59, 13 August 2025 (UTC)

To me, many of the longwinded sentences in this section felt quite staccato, in the sense that they had become somewhat convoluted, causing me to pause unnecessary to parse their meaning. I hope that option B improves flow both compared to the old text and to option A. —Femke 🐦 (talk) 20:06, 13 August 2025 (UTC)

I like the original better than either of the draft proposals for this part of the guideline. I'm sure there can be improvements to the original though, e.g. tightening up or cutting some bits. @XOR'easter do you want to take another crack at it? –jacobolus (t) 20:14, 13 August 2025 (UTC)

XOR'easter has unfortunately retired. Happy to hear more feedback though, or explain further why I made the changes I made. (I've asked David Eppstein for help with another section, fyi). —Femke 🐦 (talk) 20:25, 13 August 2025 (UTC)

Well done, Femke, it's already much improved. It was ironic that the guideline on structure was so unstructured... One small thing: the word "jargon" feels pejorative to me (implying bureaucratic or political talk designed to impress rather than to be understood); I suggest we say "technical terms", which is accurate and neutral. Chiswick Chap (talk) 08:55, 14 August 2025 (UTC)

Jargon is the accurate word for this, itself a clearly defined technical term, and I think it works okay in this kind of context. The perjorative connotation in casual settings comes from an implication that the use of jargon is intentionally or carelessly exclusive. It's kind of inevitable that any term meaning "specialized technical terms" will have such a connotation, because specialized language inherently difficult for those who haven't yet learned it – indeed, that exclusivity is what we're warning against here. –jacobolus (t) 17:52, 15 August 2025 (UTC)

jacobolus: did you have feedback for any of the other parts of the workshop text. Or can you explain what you still prefer in the old text? I've further improved flow, including a couple of short sentences. Note that some of the discussion has moved to Wikipedia talk:Make technical articles understandable/Workshop. —Femke 🐦 (talk) 11:30, 8 September 2025 (UTC)

Lead

For me, the key point about the lead is that it should not try to say everything. It's not just "Avoid adding too many details."; rather, the details to avoid are all the caveats, special cases, and exceptions that make life complicated. The lead must therefore be a deliberate (over)simplification, right in general but willing to be wrong in (unmentioned) detail. This is what "one level down" (or maybe "two levels down") implies: special cases are omitted. This applies a fortiori to the first paragraph, and even more to the first sentence. Chiswick Chap (talk) 09:22, 14 August 2025 (UTC)

I've not changed EXPLAINLEAD too much in the current draft, as it typically works quite well in getting articles understandable. The point I was trying to make, now worded more clearly, is that lenght itself can make a lead too intimidating. Like, I've seen 700-word leads that are just painful to wade through. What kind of information to omit is also important, and I agree that often the details to omit are these caveats. Have added this to a different sentence in the new EXPLAINLEAD. —Femke 🐦 (talk) 21:17, 15 August 2025 (UTC)

Introduction to

I comment the goal of making tech articles easier to understand, but I remain steadfast in my view that any and all "Introduction to" articles are pointless CFORKS (I also say the same about Simple Wikipedia...). I looked at Wikipedia:Make_technical_articles_understandable/Workshop#"Introduction_to..."_articles compared to Wikipedia:Make_technical_articles_understandable#"Introduction_to..."_articles and I don't see any major changes. Frankly, I believe such simplification should be handled by AI and like. Folks who labor at Simple, and on Introduction... type content, do great job, but it's inefficient. Simple is invisible to everyone, and Introduction... is little better. We need a major overhaul, done at software level. What I envision is that for any and all articles, a reader should have a pop-up box asking if they want a simplified version. Then they can get the Introduction/Simple variant (note: duplication of efforts that led to the creation of both, for example, Introduction to viruses and simple:Virus, is 100% a waste), or, if it does not exist, an AI generated one based on our article. Current Introduction... articles should be removed from mainspace, and kept in a dedicated space (in fact, this is what Simple... is for). In other words, we should merge all Simple content to English Wikipedia (in a dedicated namespace), merging these entries to "Introduction..." as needed, and make it actually useful (visible) to readers (through the aforementioned pop up asking what do you want, with an option to disable pop up from showing). PS. For anyone who wonders who will handle merging Simple with Introduction - AI should handle that (and we can proofread it, of course). In any case, it's time to rescue the countless hours folks spend creating Simple and Introduction, and make it actually visible. Their effort is the crown jewel of making technical (and not only) articles understandable, but it remains hidden from vast majority of readers. --_{Piotr Konieczny aka Prokonsul Piotrus| reply here} 09:06, 18 August 2025 (UTC)

I agree with you that our 11 introductory articles are not working well. The readership of these pages is often but 1-5% of their main page, even though I imagine that the audience of articles like Virus and Quantum mechanics mostly consists of non-topic experts, and having an introductory article may reduce the drive to make these article accessible. Introduction to evolution has elements I would find too difficult for the main article, and Introduction to entropy is also tagged for being too difficult. There are a few introduction articles whose existence goes against the current guideline already, e.g. Introduction to systolic geometry, Introduction to the mathematics of general relativity which does not have enough general readership to justify a separate article.

The reason I kept it in so far is to limit the number of changes to the guideline in the hope we can find consensus more easily. Looking deeper into what exists in terms of introductory articles, I'm now convinced it would be good to drop the exception to CFORK. If there are no objections, I will remove all the text surrounding introductory articles in the workshop text, which means the exception to CFORK is dropped. —Femke 🐦 (talk) 17:43, 18 August 2025 (UTC)

I agree with Femke, that this is probably not the place to discuss these types of articles, but if a more thorough discussion is started elsewhere, I would appreciate a ping. In short, I share some of Piotrus’s views, but few of his solutions. I believe the editors at Simple should decide their own fate, and I have always suspected that wiki has value even if only for those writing it. On the Intro-to- articles though, I don’t see a lot of point in their being here on en-wiki. I would far prefer editors focus on making the main article comprehensible than letting another article do that job. I see no harm in readers having access to an AI tool to summarise difficult articles, but I don’t think that’s really our job. Worth repeating as always: we are an encyclopaedia and not a replacement for all other resources.

Oh, and IMO yes, the section could go, but Femke’s least-possible-disruption attitude is sensible. Removing the section presumably removes all guidance on such articles? If so, that should probably be a broader discussion; at which point I would consider splitting the section off to its own page. — HTGS (talk) 00:29, 19 August 2025 (UTC)

Please no AI summaries at Wikipedia. Complaining about what topics other Wikipedians decide to contribute about as volunteers seems pretty pointless. Nobody needs you to "rescue" them. (But if you can figure out how to make the "Introduction to ..." articles easier to find for readers who would benefit from them, I'm sure the authors of those pages would be appreciative. –jacobolus (t) 02:26, 19 August 2025 (UTC)

This could be one of the questions in the big RfC at the end of the workshop. I plan one question per section (should workshop section A replace guideline section A'), and can make this a separate section again in the guideline and workshopped text. This would give us 6 questions, rather than 5, which I hope is still manageable. There is a single sentence about this in WP:CFORK, and will make sure to notify that page. I can start by proposing merge discussions for the introduction to articles that are not in line with existing guidelines, to make the discussion even more easy? I share the concerns about AI summaries and their lack of accuracy, and plan to organise a collaborative contest to get our leads in shape using human brains after our rewrite is done. —Femke 🐦 (talk) 06:36, 19 August 2025 (UTC)

I am fine with all of that (please ping me when/if mergers are suggested). Certainly we should leave any AI-driven solutions for another time, given the widespread anti-AI sentiment on en wiki (which would surely detract from and derail the main proposal). What I proposed above was just my thoughts on how to make the simple/intro stuff actually useful. More relevant, I believe the idea of introduction articles has failed (as you note, their readership is very small). And while HTGS is right that "editors at Simple should decide their own fate" (setting aside why we allow such de-facto useless project, but we closed up Klignon Wikipedia...), I believe that Introduction articles on en are a bad CFORK, per reasons stated (efforts to make articles better, including more understandable, should focus on the article read by 90% of the readers, not on 10%; and the long term solution needs to be different, since clearly, expecting community to create such articles has failed. That is why I favor technical solution, likely AI-driven (since humans are unwilling to deal with this)). But, yes, let's leave the AI stuff for later. For now I suggest phasing out the Introduction articles, as a weird exception/experiment that failed to produce useful (readership) results. _{Piotr Konieczny aka Prokonsul Piotrus| reply here} 12:11, 19 August 2025 (UTC)

I'm sympathetic to Femke's perspective that we don't want to derail the simplification/reorganization discussion (we need more of those!) by tacking on a potentially controversial change to "Introduction to" articles. To that end, I'd highly suggest that it be a separate RfC (although I see no reason why it couldn't run concurrently). (Also, more generally, the more you're able to break down the proposal, the less likely any one element that turns out to be controversial is to derail the whole thing.)

That said, if this guideline is going to start being used at FAC, it's overdue that we discuss the "Introduction to" problem. While I think they do provide some value to the readers who manage to find them despite our poor signposting, I agree with @Piotrus that they go against the spirit of WP:CONTENTFORK, and that as such they are not worth the huge (2x of normal articles) maintenance burden they create. And with only seven examples, they clearly haven't taken off. On AI as a solution, have you seen the discussion on the WMF's Simple Summaries feature? It came from a similar place, but, uh, did not go well. So I don't think there'd be consensus for anything like that at present.

Cheers, Sdkb ^talk 14:00, 19 August 2025 (UTC)

If there's a trivial number of these articles, then they certainly do not create a "huge maintenance burden". –jacobolus (t) 14:30, 19 August 2025 (UTC)

Ah, apologies I wasn't clear. I'm talking about the maintenance burden per article. When there is an introductory version of an article in addition to the non-introductory version, there is twice as much content to maintain as for a topic without an intro version. That is the huge increase that needs to be weighed against the value gained from the separate version. Sure, in absolute terms, the burden right now is small because there are a small number of intro articles, but so is the value gained. And when we're talking about whether to deprecate them or not, we should be considering the ultimate end state if the system is retained — scaling it to all the articles that people might deem needing an intro version would create an unmaintainable burden on our finite/stretched editorial capacity. Sdkb ^talk 14:53, 19 August 2025 (UTC)

Right. WP:ITSHARMLESS comes to mind. _{Piotr Konieczny aka Prokonsul Piotrus| reply here} 08:59, 20 August 2025 (UTC)

Last opportunity feedback before RfC

Last opportunity to give feedback before I craft an RfC statement. Do people still feel we should do a section-by-section RfC? —Femke 🐦 (talk) 21:32, 30 October 2025 (UTC)

Captions, and readers who read pictures first

A majority of readers reads captions before the main text (if Wikipedia readers behave like readers of text books and other domains). I added a sentence on this recently: As readers often examine figures and captions before turning to the surrounding text, it is usually best to avoid using newly introduced jargon in captions., which Tito Omburo removed today, saying "remove suggestion of not using jargon in captions. Images are often a way of *explaining and clarifying jargon". I still think the idea is important, but do want to encourage folks to use visuals to explain new concepts and jargon. What about wording like: Readers often examine figures and captions before turning to the surrounding text. As such, consider avoiding jargon, or repeating an explanation in the caption in other words.. What do you think of that? Happy to hear any other wording too! And please join the discussion above if you have time. —Femke 🐦 (talk) 16:44, 4 August 2025 (UTC)

I don't know what problem this is supposed to fix. Images are good, but captions should explain the image, and use technically precise language when appropriate. Tito Omburo (talk) 17:01, 4 August 2025 (UTC)

One example of where did go wrong is in the flower article, in this old version [3]. The caption assumed people know what pseudenthium is, which they can learn from the text to the left. The problem is, people will likely read the caption first and be confused at that point. That confusion might be resolved if people read the surrounding text, but there's no reason to create it in the first place. Compare that to the current caption, which teaches the jargon instead: Flower#Inflorescence —Femke 🐦 (talk) 17:45, 4 August 2025 (UTC)

Ok, but this illustrates my point: it still includes the technically precise term. It doesn't avoid it. Tito Omburo (talk) 17:49, 4 August 2025 (UTC)

Hence my new compromise wording :). Happy to hear other options too of course! —Femke 🐦 (talk) 18:01, 4 August 2025 (UTC)

It seems redundant with the rest of the guideline. There is nothing special about image captions. Arguably, it goes the other way. Image captions should include technically correct descriptions. Tito Omburo (talk) 18:15, 4 August 2025 (UTC)

Well, there is, in the sense that they are read first. Just like we describe that leads should be more understandable, and that you should put easier things up first.

There is no contradiction between my proposed text and having 'technically correct descriptions'. Understandable text is not incorrect.. —Femke 🐦 (talk) 18:43, 4 August 2025 (UTC)

I propose we avoid the term "jargon". Tito Omburo (talk) 19:29, 4 August 2025 (UTC)

Do you want to avoid use of "jargon" anywhere in this Guideline? DonFB (talk) 20:11, 4 August 2025 (UTC)

I see you edit mathematics articles, where understanding of concepts builds strongly on understanding prerequisite concepts. That is, you might expect a bit more knowledge of jargon than in other fields, and avoiding it may lose precision. Is that correct? In my original wording, I specified 'newly introduced' jargon to ensure we're not avoiding jargon that your typical reading may be fully familiar with in highly advanced topics.

I can make it more vague When writing figure captions, keep in mind that readers usually look at figures and captions before the surrounding text. That way, people can take appropriate action for their field. It might be too vague. —Femke 🐦 (talk) 20:17, 4 August 2025 (UTC)

Seems reasonable. I would not object to some language like "pay particular attention to the readability of image captions", without being overly prescriptive. But I think this might be shooting the messenger. Pointing out binding sites on a protein is legitimately important information in an encyclopedia, for example, but may not be of interest to a general reader. Tito Omburo (talk) 21:06, 4 August 2025 (UTC)

In my opinion the previous caption on the flower page is significantly superior to the updated caption. It is concise and specific, and it is immediately obvious that to understand what the word pseudenthium means one should look at the adjacent text. The new caption is distractingly long.

The problem is not the previous caption; the problem is that the adjacent text only uses the plural pseudenthia, and the relation to pseudenthium may not be obvious; the wording of the text section could also be improved. I would recommend reverting the caption change –jacobolus (t) 15:30, 7 August 2025 (UTC)

It's quite common that people only read images and captions after the lead. I don't see the point in (initially) confusing these folks myself. Especially as the article is not sufficiently understandable. Good chance readers will have given up before reaching that point of the paragraph. —Femke 🐦 (talk) 16:06, 7 August 2025 (UTC)

There's always a trade-off. The longer you make figure captions, the more visually distracting they become and the less likely someone is to attempt to read them.

If you duplicate two sentences of the article body text into every caption, in theory the figure is then more "self contained", but speaking for myself as a reader, the result feels like a poor design with low information density, and patronizing. It feels like a statement from the author along the lines of: "you're too stupid to recognize that this jargon word can be found in the adjacent text" or "I don't expect you to be capable of reading the text at all, so I decided to duplicate as much information as possible into the captions." –jacobolus (t) 16:33, 7 August 2025 (UTC)

Also, do you have evidence for your claim that it's "common" for readers who want to learn about some topic to read only the captions and skip the article text entirely? I think this is at best an oversimplified description of readers' intentions and behavior. –jacobolus (t) 16:39, 7 August 2025 (UTC)

Femke is probably correct about this. Readers normally read very little of an article (whether on Wikipedia or elsewhere), and they tend to look at photos before they look at the oblong gray blur of text. On mobile, which is nearly 70% of our page views, they don't even have a practical choice about it: the image in the "top corner" of the section is shown before the first paragraph.

There is research (e.g., based on Eye tracking) about how readers interact with articles, but AIUI none of it is very recent, most of it is based on desktop, and very little of it uses "organic" uses of Wikipedia (meaning that the researcher says 'here, read this Wikipedia article that I picked out', rather than 'here, I'm going to track everything you look at on your phone for the next three days, extract the bits that involved looking at a Wikipedia page, and then analyze real-world use'). WhatamIdoing (talk) 03:00, 14 August 2025 (UTC)

@WhatamIdoing Readers may start by looking at the images, but do they immediately read the captions? And are they more or less likely to read the captions if the captions are each a paragraph long with lots of detailed notes about the image content? When they do read the captions and they encounter a jargon word, what proportion of readers get stuck and can't figure out how to parse the jargon when it is explicitly defined in the immediately adjacent body text? –jacobolus (t) 08:54, 14 August 2025 (UTC)

It sounds like you'd be interested in expanding our under-developed article on Screen reading. Folks at the Wikipedia:Help desk might be willing to help you find some good sources for that. WhatamIdoing (talk) 17:01, 14 August 2025 (UTC)

No, I'm not interested in writing an article about how people read on screens.

My point is: the need for captions to be immediately understandable to someone with no previous knowledge and complete comprehensive descriptions of the image shown above them must be balanced by an equally great need for the captions to be as concise and legible as possible. These two essential needs are in direct opposition, so Wikipedia authors must use some discretion and finesse when writing captions (as when writing anything else). –jacobolus (t) 17:09, 14 August 2025 (UTC)

I think your new wording is solid. As a reader I can confirm the point you're making; I will also note that many (lazy) textbooks are aware of this and simply follow a jargon-y caption up with "as explained in the text". Toadspike [Talk] 05:08, 5 August 2025 (UTC)

I think Toto's point ' I would not object to some language like "pay particular attention to the readability of image captions", without being overly prescriptive.' is a good general approach. What is the message you are trying to get across, without going into specifics of how that might be achieved? Specifics might only be relevant for some captions (or other points we want to make in the guideline) or some topics. Sometimes, specifics are needed, though.

For example, not all captions explain the image. In Ketogenic diet#Indications and contraindications, I use an image caption to pull out a key message, and the photo of anticonvulsant drugs is there to accompany that and help associate it with a mental image in the reader's brain: these are the drugs a patient might have tried already before considering the diet. Such images help reinforce memorisation of those facts. Someone brighter than me might know what this technique is called. At Tourette syndrome#Society and culture, the reader is informed that "Samuel Johnson is likely to have had Tourette syndrome", and we include a painting of Johnson. I'd argue that the attempt to describe that painting with "Samuel Johnson c. 1772." is a distraction in the article, which isn't about when the portrait was done or the artist Joshua Reynolds. There are all sorts of reasons why that image was added to the section, but nothing about the image itself is illustrative of the topic or needs explaining or describing beyond linking the image with the person. -- Colin°^Talk 07:38, 14 August 2025 (UTC)

If someone wants the caption to have enough context to be read by itself, something like "18th century English writer Samuel Johnson likely had Tourette syndrome." would probably be better. But the "18th century English writer" can also be pretty safely dropped from that, considering it is discussed directly in the text. –jacobolus (t) 09:01, 14 August 2025 (UTC)

You think some of our readers might not know who Samuel Johnson was? Hasn't everyone seen Blackadder? -- Colin°^Talk 09:10, 14 August 2025 (UTC)

Presented as an example

How to make this edit consistent with Wikipedia policies and guidelines? Tito Omburo (talk) 21:39, 6 August 2025 (UTC)

The edit seems reasonable and mostly housekeeping. But I want to commend—even congratulate—you for making the first paragraph of the article a wonderfully and readily understandable real-world example, while simultaneously providing a clear synonym for the one word of jargon in the opening text. This may be the best example I've seen of an accessibly-written intro to a highly technical mathematics subject and shows a laudable willingness to accommodate general readership. DonFB (talk) 22:38, 6 August 2025 (UTC)

That is an impressive introduction. I'll try to incorporate it as an example during the workshopping for an updated guideline! —Femke 🐦 (talk) 16:22, 7 August 2025 (UTC)

Agree with DonFB and Femke, a great example of making the intro of a high level math article accessible to most of our readers. I would argue that a similarly accessible introductory explanation or example could be written for any math article, and should be. --Chetvorno^TALK 10:15, 14 August 2025 (UTC)

Note that the jargon-laced definition of the theorem, which most readers will find incomprehensible, is relegated to the second paragraph, while the simple illustration is in first place. Most editors of math articles are very insistent that the lead of the article be a rigorous definition in mathematical language. This is not necessary, and we should educate our mathematician colleagues that their articles will be read a lot more if they ease into their subject with simple explanations. --Chetvorno^TALK 10:15, 14 August 2025 (UTC)

RfC: Amending the guideline text

Should we adopt the text of Wikipedia:Make technical articles understandable/Workshop as the new text for this guideline (compare)?

• Option A adopt the new guideline in its entirety
• Option B adopt specific subsections (please specify)
• Option C keep the existing guideline as is.

—Femke 🐦 (talk) 19:07, 5 November 2025 (UTC)

Update Multiple people have suggested there should be a separate proposal for retiring introdutory articles. See the second RfC question below. —Femke 🐦 (talk) 11:45, 9 November 2025 (UTC)

Survey

• Option A. First, thanks to everyone who has helped write or provide feedback in the workshop phase, specifically Jens Lallensack, jacobolus, Phlsph7, Julius Chandler and Piotrus.
  I think the new text does many things better than the old text: it's less waffly, it provides more specific guidance based on external reference works, and it stresses the benefits of collaboration. Furthermore, it incorporates good tips from WikiProject pages on the topic. The old guideline doesn't work well for writing clearly for mobile users, as the Minerva skin promotes reading per section, rather than linearly. The new guideline gives tips on how to cater to these readers (for instance, by starting each section understandably, rather than only the first sections in articles with unavoidable complicated material). —Femke 🐦 (talk) 19:07, 5 November 2025 (UTC)

  Option D for further workshopping. There's really good comments from SandyGeorgia, Gog and Stepwise Continuous Dysfunction on how to improve this guideline further. I've incorporated minor changes to the guideline during this RfC, but more major changes should be done in a second workshop phase. I want this guideline to be accepted with wide support, so that it will be useful in discussions, rather than the status quo of some people pushing back against it because of its weaknesses. —Femke 🐦 (talk) 08:31, 10 November 2025 (UTC)

• Option A. Thank you, this is a great improvement. MichaelMaggs (talk) 20:50, 5 November 2025 (UTC)

  .. but, as indicated in the discussion, remove the list of general writing tips. MichaelMaggs (talk) MichaelMaggs (talk) 11:35, 7 November 2025 (UTC)

• Option A. Thank you, Femke, for your work.

  Julius Chandler (talk) 21:33, 5 November 2025 (UTC)

• Option A. I agree this is an improvement over the current guideline. Thryduulf (talk) 21:38, 5 November 2025 (UTC)
• Option A. Many improvements, I'm impressed. —Rutebega (talk) 21:40, 5 November 2025 (UTC)
• Option A - (yapperbot) Looks like a nice set of improvements. Suriname0 (talk) 21:47, 5 November 2025 (UTC)
• Option A, with a big thank-you to everyone who worked on this. I somehow was unaware of this until just now, when I saw the RfC listing. But it does a fine job of addressing something that has been a long-time pet peeve of mine. And good luck getting this adopted on physics and math pages (said ironically). --Tryptofish (talk) 00:56, 6 November 2025 (UTC)
• Option A Looks good! Ca ^{talk to me!} 01:07, 6 November 2025 (UTC)
• Option A Good job. My slightly jaundiced view is that it reads like a very close inverse of nearly universal practice in technical and semi-technical articles throughout the encyclopedia. DonFB (talk) 02:55, 6 November 2025 (UTC)
• Option A - Great job, that table is really nice. FaviFake (talk) 03:33, 6 November 2025 (UTC)
• Option A - Looks nice. Very clearly written. See my note below in "Discussion" about the guideline's "Use plain English" section. Noleander (talk) 13:49, 6 November 2025 (UTC)

Striking my "option A" choice, since it appears that much of the guideline applies to all WP articles, so it seems wrong to spend effort that only benefits "technical articles". Better is to adapt the guideline to apply to all articles. Noleander (talk) 01:15, 7 November 2025 (UTC)

• Option C - "Introduction to" articles are popular with readers. Graham Beards (talk) 10:58, 9 November 2025 (UTC)

  @Graham Beards. Shall I split that out to a separate RfC? I had option B in mind for people objecting to specific changes, but I may not have formulated it well. —Femke 🐦 (talk) 11:24, 9 November 2025 (UTC)

  RfCs in my experience (eighteen years here) just become voting platforms and not considered arguments. There is a place for Introduction to articles. During the pandemic Introduction to viruses peaked at over 70,000 page views a day. Obviously, I have chosen this example because I wrote it, but I also wrote most of Virus as I felt there was a strong case for both articles. Already, a notice about the possibility of "retiring" introductory articles has been posted on the Talk Page of them. I thought, and still think, that the extant section on such articles was well thought out and well written.Graham Beards (talk) 13:40, 9 November 2025 (UTC)

• Option C I looked mainly at the new draft and it seemed too verbose, starting with the nutshell. Looking at the overall pagesize stats, the existing text is 1,808 words while the new one is 2,217 – 20% longer. This bloat is contrary to WP:CREEP. See also the KISS principle and WP:TLDR. Andrew🐉(talk) 14:28, 6 November 2025 (UTC)

  I've further condensed the nutshell to Make every part of each article as clear as possible for the broadest likely audience. The new guideline text covers more ground than the previous one and is longer, so I understand concerns about WP:CREEP. If you have further examples of verbosity (waffly text) however, I'd be very keen to improve the workshopped text. —Femke 🐦 (talk) 14:45, 6 November 2025 (UTC)

  Another opportunity for making this guideline tighter & more focused is moving two sections ("Lead section" and "Use plain English") to another guideline. Those sections are generic guidance that applies to all WP articles. I suppose they got into this guideline due to historical accident? They should be moved into another guideline that applies to all articles. That would help this guideline become tighter and more focused. Noleander (talk) 14:59, 6 November 2025 (UTC)

  The WP:EXPLAINLEAD part of this guideline is likely to be the most cited part of it. I think it's rather essential to put down the principle that the lead should be the most accessible part of the article. —Femke 🐦 (talk) 17:43, 7 November 2025 (UTC)

  Agree. Removing the "Lead Section" portion of this guideline would seriously undermine the guideline's whole purpose. My perspective is that the writing in Lead (lede) sections of articles deserves the greatest care with respect to intelligibility, and that's especially true for articles about technical subjects. An explanation of best practices for writing intelligible ledes to technical articles is a vital tool for improving the encyclopedia's usefulness to its readers. DonFB (talk) 22:13, 7 November 2025 (UTC)

• Option C. The proposed new guideline looks as if it has been RfCed about a third of the way through being workshopped. It seems to me to introduce additional subjectivity and even ambiguity. If I were reviewing it at FAC I would be gently suggesting withdrawal for further work with a view to bringing an improved version back. I'll stick a couple of examples of what I think needs tightening up under Comments. Gog the Mild (talk) 22:14, 6 November 2025 (UTC)
• Option A. At the moment I quite like the subjectivity -- it allows the guideline to be applied flexibly and for editors to decide by consensus how best to implement it in a given situation, rather than giving blanket rules like "every article must have a reading age no greater than 16". I do see Gog's comments below and most are well taken, but my personal take is that the "problems" are all tolerable at least for the medium term -- if we adopted the guideline as written and then had to spend some time polishing the language, that would still be better than sending it right back to the drawing board. UndercoverClassicist ^T·C 07:41, 7 November 2025 (UTC)
• Option A Well done and thank you to everyone who had a hand in the workshopping of the content. If adopted, I think it would be very effective in curbing pretentious language while also ensuring things aren't dumbed down and deleted. Plus the fact that editors like Phlsph7 and Femke, whose excellent prose I have seen and liked a lot on WP, have contributed to the new version makes me believe even more that it would have a positive effect. HSLover/DWF (talk) 17:27, 7 November 2025 (UTC)
• Option A. It is a clear improvement from the old version with less waffly language and more detail well done to everyone who workshopped this.GothicGolem29 (Talk) 18:54, 7 November 2025 (UTC)
• Option A. Abaciscus (talk) 19:18, 8 November 2025 (UTC)
• Option C. I think the proposal should be further workshopped before making any decision about it. For example, confusion about the status of "Introduction to..." articles alone is enough to derail this conversation. –jacobolus (t) 20:36, 8 November 2025 (UTC)
• Option C per the concerns raised above that it's not ready yet. Stepwise Continuous Dysfunction (talk) 23:00, 8 November 2025 (UTC)
• Option C similar to above. I oppose removal of the whole section on "Introduction to...". This proposal is not ready yet. Please note the vote at Wikipedia:Articles for deletion/Introduction to quantum mechanics was a WP:SNOW close to retain.Ldm1954 (talk) 04:57, 9 November 2025 (UTC)
• Option D, not ready yet, but oppose Option A, say keep working. Option C seems to endorse keeping the current, which has issues as well, so I don't endorse that either, rather say -- keep working. This was a fine effort at a worthy project, but more workshop is needed with a broader audience prior to RFC. It's not ready for prime time, and most unfortunate is that, because it looks like an improvement, it seems to be gaining support, even though some of the problems are present even in the current version. The proposed version makes assumptions and over-generalizes. And it reads as if trying to be FAC, when most of Wikipedia is far off that mark.
  I strongly oppose the removal of the "Introductory articles" section; those articles serve their purpose well, and as an option, can help increase coverage and readership -- it's a good suggestion. Other:

Workshopping the workshop

1. "While comprehensive coverage remains a central goal"; what is this based on? I'm not aware of comprehensiveness being a goal anywhere except the FA process.
2. "While comprehensive coverage remains a central goal, every effort should be made to also make articles accessible and pleasant to read for less-prepared readers." Why remains instead of is? How does the second clause relate to the first; they are two different things.
3. "The lead section should use plain language" ... plain in the judgment of ... ?? If you are reading Tourette syndrome, in which waxing and waning symptoms are definitional, and don't know the meaning of wax and wane, here's the time to learn. Changing that to some awkward version of coming and going, increasing and decreasing, weakens the lead and doesn't serve the reader. "Plain language" in the lead has been -- and will be -- abused and a source of discord.
4. "For the body of the article, a common strategy is to begin with easier aspects of the subject before moving to more advanced or specialized material." Most biomedical content has a fairly well established order of presentation, and this isn't part of it -- this statement overgeneralizes (and I've never encountered it).
5. "collaboration among editors with different levels of expertise can be very helpful." Again, this page is not WP:FAC. Collaboration among like-minded editors with similar experience at FAC works well; outside of that structure, editors who don't know the content area or don't have broad knowledge of the sources can bring more hindrance than help. What works well at FAC doesn't always translate to the rest of the "anyone-can-edit" world.
6. "A well-written article will grab the interest of all these groups and let them learn as much as they are able and motivated to do." This is an assumption that might not apply to the entire article. It must apply to the lead; it applies to varying degres to different sections of different kinds of articles. The pathophysiology section in a medical article may grab the interest of very few, and unlikely all groups.
7. "An article may disappoint because it is written well above the reading ability of the reader, because it wrongly assumes certain background knowledge, or because it covers the topic at too basic a level and is not comprehensive." Again, most of Wikipedia is not FAC. Decades ago, we hoped FAC would set a standard that others would emulate: we can see it hasn't achieved that goal -- .09% ever since, never changing. This page should be aiming at the entire project -- not less than 1% of the project.
8. " For example, a topic in advanced mathematics, specialist law, or industrial engineering may contain material that only knowledgeable readers can appreciate or even understand." This sounds like we're letting some of Wikipedia's most poorly written content off the hook -- the problem with most of our math content is not the math, it's the English -- even at high-school-level concepts.
9. "Most [sections of most] Wikipedia articles can be written to be fully understandable to the general reader with average reading ability and motivation."
10. "It is unreasonable to expect a comprehensive article on such subjects to be understandable to all readers." Why are we on comprehensive again? The entire project is not FAC, and "Introduction to ... " articles don't have to be as comprehensive as the full article. This page also seems to degrade the value of links and summary style, by focusing on "comprehensive" rather than spinning off difficult pages with less readership (eg, "Causes of ... " or "Pathophysiology of ... " or "Treatment of ... " in biomedical).

    (I've read further down and now see that summary style is mentioned later, so the flow is off here and I'll leave this comment in for that purpose.)

11. "The effort should still be made to make the article as understandable to as many as possible, with particular emphasis on the lead section." WP:LEAD is a separate thing with its own page/guideline.
12. "For articles not of wide interest, write "one level down" to increase understandability." This has been and will be abused, and should not be generalized as a mandate to entire articles. It also doesn't make sense. Most advanced medical topics are only studies at the post-graduate level, so we're not supposed to make Tourette syndrome understandable for a high school student wondering why they tic, or the less-educated parents seeking information?
13. "When deciding how much technical detail to include, standard reference works in the field can serve as a guide." This seems to be made up. DUE? Expecting the mom who wants to know what Tourette's is to want the level of detail in standard reference works ????
14. Wow -- we got a call out !! Thanks ... "Overexplained jargon can make an article less engaging, so consider whether the jargon can be avoided altogether. Sometimes, the solution is to dedicate a separate section to widely used terminology (e.g. Dementia with Lewy bodies#Terminology)." OK, should I start being less critical now :) :). But the problem there is doing this for most articles would contradict following sources -- at DLB we could do this because that's what sources do, and there are sections of sources devoted to terminology -- will that work everywhere? (Asking, I don't know.)
15. "Avoid jargon by replacing it with plain English alternatives, ". Has been and will be abused. "Wax and wane" -- the simplest, most basic part of understanding what Tourette syndrome looks like -- is no longer in the lead, and that was not a fun experience. The article is worse for it. This page later says, "It is important not to oversimplify material in the effort to make it more understandable", and that's what happened to "wax and wane".
16. "Only rely on wikilinks on their own when you expect most of your readers to already be familiar with the term" ... somewhere, this page should say something about never expecting a reader to click out to understand a sentence.
17. Use plain English. "Communicating technical content in plain English benefits everyone ... " This is an assumption I don't think is true, and I know several other FA writers who don't either, after seeing medical FAs downgraded by attempts to convert highly nuanced concepts to plain English, losing accuracy in the process. There are sections where precision matters and plain English might not suffice. The amount of certainty written in to this page is sure to lead to disputes of the kind we've already seen in medical content.
18. "Use short sentences, paragraphs and sections. " Strong oppose as written; the page now says, "Use some short sentences and short paragraphs." Here's an example of a "headache-inducing" mandated use of short sentences:

    I mean, I was looking at the lead for Harlequin-type ichthyosis:

    "There is no cure. Early in life constant supportive care is typically required. Treatments may include moisturizing cream, antibiotics, etretinate, or retinoids. It affects about 1 per 300,000 births. There is no difference in rate of occurrence between sexes. Long-term problems are common. Death in the first month is relatively common. The condition was first documented in 1750."

    It gave me a headache. So yes, perhaps changing the medical lead guide to specifically include WP:TECHNICAL's statement, "However, using too many short sentences in a row becomes monotonous; vary sentence length to maintain reader interest" would be helpful. SUM1 (talk) 08:51, 19 January 2020 (UTC)

19. "Avoid overuse of 'former' and 'latter', as readers have to go back to the previous sentence." Similar should be added for "respectively" ...
20. FLow is off .. this could be stated much sooner: "It's perfectly fine for later parts of articles to be more technical, if necessary." But this isn't necessarily so ... "Those who are not interested in details will simply stop reading at some point, which is why the material they are interested in needs to come first." Pathophysiology goes where it makes sense -- it doesn't have to come after the relatively easy "History" section of medical content. Over-generalized.
21. "Analogies and comparisons" seems to encourage original research ... one is lucky to find a useful analogy in a source.
22. The page should introduce the need for consistency. If the article uses plain words then technical language in parens or brackets, it shouldn't later switch to technical terms then plain words in parens or brackets.

With the competence behind this effort, I think the next version can make it -- after toning some of the mandate, correcting some of the overgeneralization, avoiding pitfalls that will be abused once endorsed via RFC. Best of luck, SandyGeorgia (Talk) 00:53, 10 November 2025 (UTC)

• Option A, I quite believe in the spirit of the guideline and think that the letter is also good. If it became a guideline, then it would gain more visibility and this guideline would benefit many people who may not have the best English skills, but still wish to learn more about something.
  Additionally, although not necessarily, it could lead to the shutting down of the Simple English Wikipedia. I think Simple is in a much worse situation than English, and that it is an unneeded content fork of the English Wikipedia which is perpetually vandalized, mediocre, and lacking improvements to the point of uselessness. Although I don't think that just because this essay becomes a guideline, that the Simple English Wikipedia will cease to exist. Nonetheless, if this becomes a guideline, it would become widely followed. Consequently, more English wikipedia articles would be written in a simple and understandable way, meaning that Simple would become obsolete and could be merged back into English. Though this is a really far off into the future thing, and that regardless of the fate of Simple, the officialization of this essay would be a positive. User:Easternsahara_{review and this} 01:42, 11 November 2025 (UTC)

  Hello Easternsahara: the RfC is not about upgrading an essay to guideline. It's about replacing the existing guideline text with new guideline text. The guideline also does not replace the function of simple, as the text there is really pointed towards people with limited vocabulary. —Femke 🐦 (talk) 08:11, 11 November 2025 (UTC)

• Option C – I agree that there are problems with the current guideline, but this revision raises more questions than it answers. I specifically object to the 'Use plain English' section, as overly prescriptive. Take this back to the drawing board. Yours, &c. RGloucester — ☎ 05:21, 13 November 2025 (UTC)
• Option C – do as individual edits instead. There is lots of decent stuff, but this has some issues and seems just a diverse and big grab bag of various bits of edits without particular theme or goal, plus much of ok-wording version 1 to ok-wording version 2 doesn't seem much different, so does not seem appropriate to view as a "substantive edit" or to do in one lump. Some individual points from looking at the Difference between pages

Keep the disambiguation link to Wikipedia:TECHNICAL (disambiguation)

Keep "upholding the goals of accuracy and full coverage of the most important aspects of a topic" preface separate from the guideline "effort should be made to also make articles accessible and pleasant to read for less-prepared readers".

Change - "The lead section should use plain language" would more appropriately link to MOS:INTRO

Change - move and redo the blurbish "Some articles are themselves technical in nature and some articles have technical sections or aspects. Many of these can still be written to be understandable to a wide audience." into a directive form at the lead paragraph such as 'This guideline is for articles that are technical or have technical sections or aspects, to detail how they should be written to be understandable to a wide audience."

Keep the subtitle "Avoid overly technical language" for the section which has content saying "avoid overly technical language" - the content is not about limiting it.

Keep the bullet form for "Avoid overly technical language" - the added two lines can be dropped as just vague blurbs saying sort of what distinct 5 numbered items or 7 bullets are better at -- and the 7 bullets do not seem replaced by the 5 items, so I'm not sure that is good either.

Conflict ? - the 'Use Plain English' subsection 'Avoid long sentences, paragraphs and sections' is mismatched with content talking about how only using short sentences impedes flow.

Avoid generic 'some' -- e.g. 'sometimes' in "Sometimes it is useful to use analogies" as vague and not directive. It is better in the prior form of a distinct guidance to "Use analogies to describe a subject in everyday terms."

Cheers Markbassett (talk) 23:37, 13 November 2025 (UTC)

Thanks for detailed feedback Markbassett. There's two points I don't understand: What do you mean with your point on "Upholding the goals of"? I've switched the sentence around and made rewrote it in simpler prose. And what do you mean with the bullet points? I've expanded on how you can avoid / explain jargon (first subsection) and how to use simple prose (third subsection). There's been some objections to the heading 'use plain English', as plain English also captures avoiding jargon. I've added the disamb link (never intended to delete that), and renamed 'Limit technical langauge' back to the more wordy 'Avoid overly technical language', as there were more objections. —Femke 🐦 (talk) 08:18, 14 November 2025 (UTC)

From the link at the top where it says "(compare)"

- The second line "While upholding the goals of" current phrasing has the guidance about making technical articles understandable in a separate and subordinated "also make articles accessible". I felt that the proposal was merging both into one guidance "make articles accessible and pleasant to read for less-prepared readers, without losing accuracy" was mushing too much together, folding in something not about the understandability topic for this guideline and lost the priority or limit phrasing. In the prior case, one should always keep full coverage of the most important parts and do the best you can about understandability, but the newer phrasing on the same level would allow tradeoff judgements of dropping a few of the important parts if what was left was greatly more understandable. That seemed contrary to encyclopedic coverage and WP:WEIGHT concerns.

- The section "Avoid overly technical language" currently uses a presentation format of seven bullets, and the proposal uses a numbered list of five items with two paragraphs of text before and one after. I felt that bullets are more appropriate than numbering since that's less intrusive and the list is a collection and not a sequence of steps nor a construction with totality 5 parts. As an unrelated aspect, I also felt having the more guidance items was desirable.

- "Plain English" - well, there are somewhat differences between Plain English clarity and Plain language simplicity. I would offer that perhaps the article lead should say something but perhaps in words not using a label phrase, e.g. 'The goal in technical articles generally is creating clear, concise documentation that explains complex information to the readers. This article provides guidelines to do that for Wikipedia articles on technical topics or parts of articles that are technical, while also avoid having articles read like a manual, guidebook, textbook, or scientific journal. ' Then the guidance can freely have bits about both -- either English grammar features like familiar words, active voice, reducing punctuation, conversational style, and short sentences -- or about article audience, article structure, and reading or jumping to subtopics quickly.

Cheers Markbassett (talk) 20:26, 14 November 2025 (UTC)

Discussion

• The new version does not seem to discuss the concept of "Introduction to" articles at all - is this correct? --_{Piotr Konieczny aka Prokonsul Piotrus| reply here} 12:16, 6 November 2025 (UTC)

  That's correct. The main article should be sufficiently understandable. —Femke 🐦 (talk) 12:23, 6 November 2025 (UTC)

  @Femke What would happen to existing introductory articles? fgnievinski (talk) 16:14, 8 November 2025 (UTC)

  Depends on whether people have time or not, but ideally the two are merged, with the main article accessible to the widest likely audience. —Femke 🐦 (talk) 16:17, 8 November 2025 (UTC)

  I believe the deprecation of introductory articles should be more widely advertised, by tagging such articles and related templates and categories. fgnievinski (talk) 16:44, 8 November 2025 (UTC)

  Ugh, this seems like a bad direction to be going in. I think there's plenty of room for multiple articles about a subject aimed at different level audiences. RoySmith (talk) 16:57, 8 November 2025 (UTC)

  I feel that having an introductory article takes away the pressure from the main article to be accessible. I wouldn't be too opposed to the reverse, like advanced quantum mechanics or so (with a better title), where the main article is written for a wide likely audience. —Femke 🐦 (talk) 17:00, 8 November 2025 (UTC)

  Some topics are so broad as to be impossible to have a single article which is broad enough to be useful to all readers. Physics is a good example. RoySmith (talk) 17:05, 8 November 2025 (UTC)

  takes away the pressure – this is completely unsupported by any evidence or analysis. –jacobolus (t) 17:54, 8 November 2025 (UTC)

  I have now left a note on the category talk and on WT:CFORK. —Femke 🐦 (talk) 17:05, 8 November 2025 (UTC)

  Thank you for that. Can we have a separate subsection heading for discussing the deprecation of introductory articles, please? I intend to tag each such an article, before their fate is sealed. fgnievinski (talk) 17:27, 8 November 2025 (UTC)

  The way I set up the RfC is to include option B if people object to specific sections being replaced or removed. Not sure if an additional question is needed. Happy to hear more people on this though. —Femke 🐦 (talk) 17:35, 8 November 2025 (UTC)

  @Femke @Fgnievinski For the record, I support deprecation of such articles, per my arguments at CFORK and here from while back. But this is something that should be discussed in a dedicated place. Just writing them out from here is not the same as depraciation. But we should check if the ""Introduction to..." article" section has been linked to, and perhaps retain it with a note that they have been depreciated, or such. I don't see any shortcut to this section, but just erasing it is less than ideal, it's a bit like hiding the problem under the carpet. Btw, I did check the redirects and I see the following: Wikipedia:Introduction articles, Wikipedia:Introductory articles and Wikipedia:INTROTO, linking here. A temporary solution would be to split the existing section into a separate article (maybe one of the two linked above), update the other two redirects, and then discuss the fate of introduction articles there (with links from here and CFORK). _{Piotr Konieczny aka Prokonsul Piotrus| reply here} 05:15, 9 November 2025 (UTC)

  What to do with the introduction articles is way out of scope for this proposal, and frankly all that relevant to this guideline either. –jacobolus (t) 17:53, 8 November 2025 (UTC)

  As the proponent explained above,introductory articles are expected to be at best merged as a consequence of their deprecation. My concern is the present discussion might be misinterpreted as justifying the expedite deletion of such articles. fgnievinski (talk) 18:01, 8 November 2025 (UTC)

  This proposal doesn't say anything explicit about the "introduction" articles. Taking any decision about it to imply their deprecation would, in my opinion, be an absurd conclusion, not according with any demonstrated consensus. –jacobolus (t) 20:37, 8 November 2025 (UTC)

  The proposal seeks to remove the whole section about introductory articles from the present editing guideline. Such a guideline removal will likely be (mis)interpreted as if prohibiting the creation of new introductory articles. Indeed, WP:CFORK was mentioned by the proponent and others as justification for eliminating introductory articles. fgnievinski (talk) 02:55, 9 November 2025 (UTC)

  I am going to oppose removal of the whole section on "Introduction to". This will create monsters that are far too long and impossible to maintain. In effect the removal would mean that many articles would almost have three to four parts:

  1. Lead
  2. Introduction for the novice
  3. Encyclopedic information for people with some knowledge
  4. Encyclopedic information for the expert

  Please note the vote on Wikipedia:Articles for deletion/Introduction to quantum mechanics was a WP:SNOW close to retain. Ldm1954 (talk) 04:50, 9 November 2025 (UTC)

  I agree with the argument made a few sections up this page that having an "Introduction to such-and-such" article is not morally different from spinning off a "History of such-and-such" article. History of physics is not a content fork of Physics, and History of quantum mechanics is not a content fork of Quantum mechanics. If we can have a principal article with a "History" section and an ancillary one that expands upon that section, we can have a principal article with an "Overview" or "Introduction" section and an ancillary article that expands upon it. Excising the section of this guideline that advises creating such spin-outs would be excising helpful advice. Stepwise Continuous Dysfunction (talk) 06:42, 9 November 2025 (UTC)

  All articles in Wikipedia are subject to the General notability guideline. I believe that both Introduction to quantum mechanics and quantum mechanics are topics that have "significant coverage in reliable sources that are independent of the subject" and thus would not be merged absent specific consensus to do so. (These articles do not achieve the goal of summarizing knowledge in their arenas, but that is a independent problem). Johnjbarton (talk) 04:03, 9 November 2025 (UTC)

  Indeed, that's a useful notability criterion for introductory articles: has the subject attracted significant coverage in reliable independent sources meant for a general audience, such as popular science sources? fgnievinski (talk) 01:43, 11 November 2025 (UTC)

• The "Use plain English" section applies to all articles, not only technical articles. I understand that section was already in this guideline (before this proposed change), so I'm not suggesting it be removed. But maybe, in the future, that section should be moved to another, broader guideline (maybe the MOS? but that doesn't seem like the best location for it). Noleander (talk) 13:47, 6 November 2025 (UTC)

  I would love for there to be a WP:READABILITY guideline, and have a start of a draft lying around somewhere. The recently created WP:Readability tools is a step in that direction, even if it may be more critical of the automatic tools for a widely supported guideline. I would like to keep the text here for now if it cannot be moved to another guideline now. I have ever so slightly shortened it however :). There is a reason to keep some of it in this guideline: people can usually deal with a limited number of complicated things at the same time. Having verbosity in a history article is less damaging than having it in a maths article. —Femke 🐦 (talk) 17:22, 6 November 2025 (UTC)

  The section wasn't already in this guideline; it's a new addition. –jacobolus (t) 19:01, 6 November 2025 (UTC)

  Around half was in the previous guideline, but it's now a separate section as not all of the current tips are about reducing jargon. —Femke 🐦 (talk) 19:17, 6 November 2025 (UTC)

• Some words have a different meaning for experts than for non-experts. For example, an uncertainty interval indicates how confident scientists are in a certain finding, but the word uncertainty may imply the opposite to readers. Avoid these terms whenever they could create ambiguity, or, if that is not possible, explain. [... a table here ... ] It is not clear if "avoid these terms" is referring to all words that have different meanings, or only to the five words appearing in the following table. I'm guessing the intention was "all such words", but some readers may think it only applies to the five. Noleander (talk) 13:58, 6 November 2025 (UTC)

  I've changed the text to "Avoid such terms" to clarify. —Femke 🐦 (talk) 17:18, 6 November 2025 (UTC)

  This guideline cannot be applied because it contradicts the policy WP:Verify. Almost all scientific articles will use these words, they have specific meanings, and any substitute will make verification fail. Johnjbarton (talk) 03:27, 9 November 2025 (UTC)

  The guidelines calls for explaining terms or substituting them only when they create ambiguity. And paraphrasing is allowed. For instance, you can explicitly say "statistically significant" or "large", depending on what the source means. —Femke 🐦 (talk) 07:46, 9 November 2025 (UTC)

  Umm, I want to mention that guidance needs to be flexible at least in part to handle some topics (all topics with disputing sides) where language is weaponized and the technical meaning is mixed up with the informal meaning. My example would be where an advocacy group (by definition PR stunts and spin/framing tricks) said Evolution was "just a theory", with "theory" misleading because the formal scientific definition of "theory" is quite different from the everyday meaning of the word. And then an opposing advocacy group (still PR stunts and spin/framing) did one-upmanship misleading of "Evolution is both theory and fact", conflating change over time examples with the various mechanisms and multiples with singular, still misleading by everyday meanings of the word. To make anything clear sometimes needs the technical phrasing present with it's meaning used or explained, and how WP:V or WP:WEIGHT is applied would have to take some care when there are proponents at odds. Cheers Markbassett (talk) 21:08, 14 November 2025 (UTC)

• I'm late to the party, so forgive me if this has been covered before, but I've often felt it would be useful to have "intended audience" ratings for articles. Maybe it's OK to have some articles which are not intended for a general audience. I think we would often serve our readership well to say something like "This article is written for people who have a post-graduate level understanding of topic X. For a more introductory treatment, see This other article" RoySmith (talk) 14:06, 6 November 2025 (UTC)

  Do you know about these Roy? Category:Introductory articles Graham Beards (talk) 14:24, 6 November 2025 (UTC)

• I'm not a huge fan of § Limit technical language as a heading; it seems open to misinterpretation. Maybe the previous "Avoid overly technical language" wasn't ideal either, but at least the "overly" hints that technical language is often unavoidable. –jacobolus (t) 18:03, 6 November 2025 (UTC)

  In this section, I don't really like the example Avoid scientific notation that is unfamiliar to many readers: 'Dodson (1998) argued that' ⇒ 'In 1998, Dodson argued that'. – These two examples are substantially different. The first is using the name "Dodson" as a reference to a book or research paper (rather than a person, per se), with the specific source identified as a parenthetical year (so it can be found in a bibliography). The second example instead uses Dodson as a reference to a person, and moves the year to the front making it seem like the year is the most important feature here, rather than just a bit of identifying metadata. In many possible contexts, the former example would be more suitable and clearer than the latter, and in general doing a mechanical replacement of the first form for the second would be completely inappropriate without significant rewriting effort. Additionally, I don't think a parenthetical year should really be used as an example of obscure "scientific notation"; especially if there's a wikilink on Name (year) that navigates to the source, this shouldn't be a particular challenge for readers to make sense of. There has to be some better example of hard-to-read advanced notation. –jacobolus (t) 18:13, 6 November 2025 (UTC)

  I've removed the example, as I don't think it's that important, and you're right the emphasis changes between the choices. The use of parenthetical citations was deprecated on Wikipedia a few years back, so there's not that fallback for readers (and readers rarely click links to references). —Femke 🐦 (talk) 18:53, 6 November 2025 (UTC)

  The use of parenthetical citations as a primary means of providing references was "deprecated", but that doesn't mean we can't ever use the relevant templates from within an article. In particular, it remains useful in cases where some specific article or book is a subject of the sentence rather than just a source for a claim, as happens e.g. in sections that are mostly historical literature review. –jacobolus (t) 18:56, 6 November 2025 (UTC)

  Fair. —Femke 🐦 (talk) 19:21, 6 November 2025 (UTC)

  My interpretation of "scientific notation" is along the lines of technical abbreviations, like the one in parentheses ("au") that I supplemented with a plain English distance description in the Webb Telescope article: Special:Diff/1061722659. Another type of techy notation is of the type I replaced in the Draco article: Special:Diff/1317845193. DonFB (talk) 23:10, 6 November 2025 (UTC)

  Why is the list in this section numbered? Do the numbers / ordering mean something? –jacobolus (t) 19:07, 6 November 2025 (UTC)

  Yes, they go from most simple (avoid jargon) to most complicated (only provide a wikilink). —Femke 🐦 (talk) 19:21, 6 November 2025 (UTC)

  The numbers seem confusing and distracting. YMMV. –jacobolus (t) 19:31, 6 November 2025 (UTC)

• § Words with different meanings – can we find concrete examples in context from (past or current) Wikipedia articles that were open to misinterpretation or confusion and then fixed to be more understandable without compromising the meaning, instead of making up speculative examples? –jacobolus (t) 18:19, 6 November 2025 (UTC)

  These are based on standard examples given in science communication seminars, and the three science communication books I consulted for the rewrite. The ones I frequently encounter are overuse of 'uncertainty' in climate change articles, the ambiguous use of significant in medical articles, and theory in topics with wide misinformation (evolution/climate change). If there are better examples you're familiar with, I'm keen to hear it! —Femke 🐦 (talk) 18:28, 6 November 2025 (UTC)

  My point though is: Can we give concrete examples from Wikipedia articles including a before/after of a specific change? Examples pulled out of context from uncredited seminars aren't necessarily practical to apply: we certainly shouldn't rush to remove all examples of the words "theory", "model", "significant", etc. used in a technical sense from English Wikipedia. –jacobolus (t) 18:33, 6 November 2025 (UTC)

• § Use plain English – this section is too rigidly prescriptive, like a chunk of Strunk and White was accidentally plopped into our guideline. The guideline itself doesn't even really follow the advice listed, and without significant application of nuance and taste it isn't broadly appropriate for encyclopedia articles; in my opinion strictly enforcing this advice across the project would make the encyclopedia significantly worse; I think this section should be substantially rewritten (with much more feedback from a broader group of editors, maybe on the village pump or similar) or removed. –jacobolus (t) 18:31, 6 November 2025 (UTC)

  How are tips prescriptive? The bullet point is introduced with the words: "A few tips for writing clearly". Is there anything I can else I can add or remove to ensure people use common sense? —Femke 🐦 (talk) 19:10, 6 November 2025 (UTC)

  An official page like this will inevitably be misinterpreted to mean that every use of passive voice should be replaced with active voice, that a sentence with more than fifteen words or a paragraph with more than x sentences must be split apart, that all redundant information must be excised, or that the word "terminate" is now banned from Wikipedia. All of these kinds of decisions depend on context and involve trade-offs which can't be concisely boiled down to a one-sentence "tip". –jacobolus (t) 19:24, 6 November 2025 (UTC)

  I've seen disputes over passive voice, which is endorsed by MOS:PASSIVE.

  "Use simpler synonyms" is not specific to (or even particularly related to) technical subjects and therefore should be addressed elsewhere. In some subjects, the "complicated" synonym is the idiomatic one (and an idiom is not exactly a phrase that doesn't translate literally). Abortions terminate pregnancies; they don't merely end them.

  The 15-word limit is inappropriately described, as "understanding 90% of 15-word sentences" is not what most people call "understanding starting to fall".

  At least two instances of the word where in this draft violate the advice in this section. The word where should only be used for locations. It should not be used as a non-literal synonym for if, when, or that. WhatamIdoing (talk) 04:11, 10 November 2025 (UTC)

  "Use bullet points where appropriate to organize complex information and highlight key points." is pretty vague. How does someone concretely apply that advice? When is a list appropriate? Does a bullet list really help with organization or or emphasis, and how? Under what circumstances would a list be more distracting or confusing than prose, and what effect does listifying a section have on future editing?

  The update is better than the previous "Use bullet point to split up long sentences, but avoid paragraph-length bullet points." which was outright bad advice. But whether or not to use bullet lists, and how, is a pretty complicated topic, and this should probably be covered in more detail on a different page. There are some helpful caveats at MOS:PROSE. –jacobolus (t) 19:14, 6 November 2025 (UTC)

  While I'm overall strongly in favour of the proposal, I would much prefer this list of general writing tips to be removed for now, and eventually replaced by a link to a separately-discussed page that applies to all articles. Although phrased as 'tips' they are nevertheless highly prescriptive, and are typical of academically discredited (but enduringly popular) American style guides such as Strunk and White. The blanket recommendation to "use active voice rather than passive voice", for example, is characterised by our own article on the passive voice as "almost always based on these commentators' misunderstanding of what the passive voice is". The advice on bullet points is too simplistic, as it recommends a list format that WP:CULTURALREFS warns can become a trivia magnet when used for cultural references, which can of course be present in technical articles. MichaelMaggs (talk) 11:24, 7 November 2025 (UTC)

  I've removed the passive voice tip, per 3 objections here. The advice on keeping sentences short and avoiding redundancy already covers those cases where the passive voice is not recommended. I think it's unlikely people will be using the bullet point for culturalrefs in the kind of articles we're talking about. Given the prominence in science communication books on the topic, I am keen on keeping in the non-prescriptive tips. —Femke 🐦 (talk) 11:33, 7 November 2025 (UTC)

  One possible idea would be to pick a Wikipedia featured article about a technical topic that seems pretty accessible (or pick a technical article in some highly regarded third-party reference work aimed at a general audience) and go through rule by rule looking for whether these rules are followed in practice by good examples.

  For example, to better understand advice about sentence and paragraph length, distill each paragraph in an article down to the number of words in each sentence, and group these lists by section. For the two comments above this one, by MM and Femke, the sentences have lengths [41, 26, 37, 36] and [11, 20, 23, 19], respectively. For an arbitrarily chosen paragraph from an arbitrarily chosen featured article (Gas metal arc welding) I get sentence lengths of [31, 38, 41, 31, 17, 30, 37, 29, 12]. I found this paragraph to be pretty clear, and while it could be moderately rewritten for concision and accessibility, or even plausibly split into two paragraphs, its longest sentence, "As in globular welding, molten droplets form on the tip of the electrode, but instead of dropping to the weld pool, they bridge the gap between the electrode and the weld pool as a result of the lower wire feed rate." seems pretty accessible and I don't think it would benefit from being split apart. Advice such as "Understanding starts to drop when sentence lengths exceed 15 words" is liable to be misinterpreted without a more nuanced discussion about how some sentences express inherently complex thoughts and some paragraphs organize quite a few sentences which are naturally grouped; splitting apart sentences or paragraphs based on prescriptions about length can sometimes make make them less effective at conveying their intended message. –jacobolus (t) 16:23, 7 November 2025 (UTC)

  The FA criteria do not explicitly include understandability. Some people argue that the engaging prose criterion encompasses it, but explicit reviews on accessibility are often absent. The FAC process attracts smart people, especially in technical topics. What's engaging for them will be different from what's engaging for readers. An article like gas metal arc welding will attract people in practical jobs who are not necessarily as well-read as the folks at FAC. I think that article is far from accessible.

  I needed to read that sentence about 6x before I think I understood it. To be fair, the first 3 times I was relatively brain fogged, but me being brain fogged cancels out my higher-than-average education I'd guess. The current guideline advices an average sentence length of 12, which I believe is too strict for the typical Wikipedia audience. For instance, the UK government says that comprehension only starts to drop off from 14 words a sentence. What I hope that people take away from this is that the number where comprehension starts to drop is lower than they might experience or expect.

  The 12-words on average hasn't led to problems, so I expect a more reasonable 15 words won't cause problems either. —Femke 🐦 (talk) 14:28, 8 November 2025 (UTC)

  You needed to read the sentence about welding 6 times to understand it? I am pretty skeptical.

  In any case, feel free to propose an alternative way of breaking this down into sentences that you think would convey the same information while being significantly easier to follow. I think the issue is the inherent complexity of the message, not whether it is written as 1, 2, or 3 sentences.

  What you are crediting as "the UK government says" is a blog post about helping people write copy for a particular government website, and their cited source ("Writing guru Ann Wylie") is a now-dead blog post from a public relations association selling that author's paid courses teaching people to write press releases, which mentions in passing (without elaboration) the same API study under discussion before.

  None of these sources would come close to meeting WP:RS, and the way you keep characterizing them is, to be frank, grossly misleading.

  As for the current guideline's observation that sentence comprehension declines after 12 words: I would recommend removing that from the page unless it is elaborated; it seems to be a version of a claim from the same API study we've been discussing, filtered through various uncredited websites. –jacobolus (t) 20:50, 8 November 2025 (UTC)

  About that long sentence: I would expect some denizens of ivory towers to struggle with such text, because it's a hands-on, practical description of a process that most of them have never seen. I would expect that people who arrived at the article already knowing what a weld pool is to figure it out. This may be an example of writing "one level down": It's not about your general education or your IQ. It's about whether you know anything about the specific subject matter. WhatamIdoing (talk) 04:28, 10 November 2025 (UTC)

  I looked further into the sentence length thing, and frankly the listed source is not adequate for this. From a glance it seems to be a sort of self-help-for-scientists book about how to do effective marketing etc., and it mentions a study off-hand without a link to the study directly. From other online searches the study, by the American Press Institute, was apparently titled "Readers' Degree of Understanding". Can someone find a copy of this study, because the way it is presented in sources like this smells like bullshit to me. The claim is that, in some analysis of many newspaper articles:

  on first reading, readers typically understand 100% of the information in eight-word sentences, 90% in 15-word sentences, 50% in 28-word sentences, and 10% of the information in 43-word sentences.

  I'd really like to see more about the methodology here. Without enough detail for readers to make sense of the actual claims of this study, I am strongly opposed to passing it along uncritically in this guideline.

  In particular, it doesn't seem from the summaries presented elsewhere like this study did any kind of comparison of understanding of the same set of claims split apart into sentences in different ways, so there's a huge selection bias here. Obviously a set of sentences like "A bat bit a man. The man got sick. The man's friends got sick." is going to be easier to parse than "One possibility promoted by virologists, based on phylogenetic analyses and the location of early disease clusters, is that the virus first passed to humans when a rural farmer was bit by an infected bat." – the latter version contains significantly more information and context. But it's not obvious that the latter version would be easier to understand if broken down into 4 or 5 sentences. –jacobolus (t) 21:18, 7 November 2025 (UTC)

  I've included some more information (it's about newspapers, unsurprisingly). The study is quite widely cited, but unfortunately not available on the API website or in any libraries I have access to. There's a slightly more expanded explanation of the study in this blog. At the end of the blog, you see perspectives from various writers on what makes a good sentence length, showing that many do not exceed 15 by much. I'm strongly opposed to removing any kind of guidance on this, but if you are aware of a better source, I'm all ears. —Femke 🐦 (talk) 15:07, 8 November 2025 (UTC)

  This blog post doesn't say anything further about the API study. It just quotes various people's (inconsistent, heuristic) advice about sentence lengths.

  It also gives an example bad sentence:

  The relative importance of and relationships between design processes and production/delivery processes depend upon many factors, including the nature of the products and services, technology requirements, issues of modularity and parts commonality, customer and supplier relationships and involvement, product and service customization, and overall company strategy.

  But the problem with this sentence is not primarily its length. It's main problem is that it was apparently written by a committee of corporate zombies to take up as much space as possible while saying nothing. It has no concrete detail, no structure, and no obvious message, but just a string of vague slogans strung together incoherently. It would best be replaced by no sentence at all. –jacobolus (t) 21:00, 8 November 2025 (UTC)

  I don't think a single study, even if higher-quality than this one appears to be, is sufficient to say that "reading comprehension drops off after 15 words" in wiki-voice. Stepwise Continuous Dysfunction (talk) 22:56, 8 November 2025 (UTC)

  I'm pretty sure that one of my high school English teachers routinely required a minimum of 20 or 25 words per sentence.

  If you want to have more fun, what counts as a single word? Is high school one word, or two?

  There's decent research indicating that reading comprehension goes up if you increase the font size. This suggests that if we want better reading comprehension, we should increase the default font size (which we can do, as a technical matter).

  According to this news-focused study (and Wikipedia:Manual of Style/Lead section#Comparison to the news-style lead, half of readers understand 28-word-long sentences. Realistically, our audience is people with average or better reading skills, so if we need to say something about sentence length (which I doubt), I'd be inclined to present the median, instead of focusing on the 10% lowest-skill readers.

  We also don't need to rely on this one source. The International Plain Language Association recommends an average sentence length of 15 to 20 words, and a maximum length of 30 to 35 words.[4] The US NIH recommends a maximum average of 20 words.[5] There are also journal articles about this (example). WhatamIdoing (talk) 05:07, 10 November 2025 (UTC)

  I've emailed API requesting they put the research online. Fingers crossed. I would be curious what they say! —Femke 🐦 (talk) 20:14, 8 November 2025 (UTC)

• The draft seems to have switched from American spellings to mostly but not always British spellings. Is that intentional? –jacobolus (t) 18:47, 6 November 2025 (UTC)

  Not intentional, no. I'll switch it back to American spelling if that was the original per WP:ENGVAR. —Femke 🐦 (talk) 18:54, 6 November 2025 (UTC)

  According to LibreOffice, it's all American English now! —Femke 🐦 (talk) 19:07, 6 November 2025 (UTC)

• Following on from my !vote, some comments on just the lead and the first two subsections - which is a little past the point where under different circumstances I would have left a bold Oppose and taken it off my watchlist.

• The nutshell does not say the same thing as the opening sentence. ("the broadest likely audience" and "the widest possible general audience".) Either allows for subjectivity, perhaps unavoidably so, but this permits two editors with clear differences to both, correctly[!], claim to be following the guideline.
• I have never been persuaded of the helpfulness of Write one level down, and here "write 'one level down' to increase understandability" seems to me to contradict both the nutshell ("Make every part of each article as clear as possible for the broadest likely audience.") and the opening sentence ("Wikipedia articles should be written for the widest possible general audience.").
  • Based on a comment you made months ago, I've put in a new phrase there "For articles not of wide interest". I tried to convey that articles like 'Alzheimer's disease' should be written at the easiest level possible that makes it still sound serious, whereas a topic like Quantum chromodynamics should be described for a physics undergraduate. I can make this more explicit if you'd like. —Femke 🐦 (talk) 08:41, 7 November 2025 (UTC)

The trouble I have with "Quantum chromodynamics should be described for a physics undergraduate" is that this contradicts "Wikipedia articles should be written for the widest possible general audience." I don't see that fine tuning the difference would help. Hence my comment that this seems to have been RfCed prematurely. IMO the community needs to choose one of those approaches as a guiding principle. As things stand I suspect a lot of !voters are over focusing on part of the guidance, thinking "Yeah, I could live with that", and not realising that down the road their view is likely to be contradicted by a different sentence from the same guidance. Gog the Mild (talk) 13:48, 7 November 2025 (UTC)

• "rather than relying heavily on links." What purpose does "heavily" serve here? How does one tell when text is relying heavily on links; one editor's heavily is another's necessary. Where does it marry up to the MoS policy MOS:NOFORCELINK: "Do use a link wherever 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."?
  • Agree, the wiggle room is already there with 'largely' in the previous bit, so removed heavily. —Femke 🐦 (talk) 08:41, 7 November 2025 (UTC)
• "Other topics are intrinsically complex or demand substantial prior knowledge. It is unreasonable to expect a comprehensive article on such subjects to be understandable to all readers." A crunch point - and contradicting the opening sentence but not the nutshell. Some guidance on how to decide what falls into this category would be most helpful. Currently it seems to give an editor a licence to write incomprehensively and then hand wave that the topic requires prior knowledge. Which all topics do, we are here to provide it.
  • That's a good point, but can use some help in rephrasing. The way I interpret this is that if there is an inherent trade-off between comprehensiveness and understandability, the text should still be accessible to 95% of likely readers (aim for 100% for the lead). The 'all readers' here is a bit ambiguous. Does this mean the likely audience who happen upon the article? Or the general public. Keen to hear suggestions, as I'm not quite sure how to improve this wording.

My opinion is that the nutshell should be replaced with the opening sentence (perhaps adding "every part of each" to the front) and that this be used as the guiding principal to ground the rest of the guidance. (By coincidence I was listening to a public radio podcast while exercising this morning and there was a perfectly good explanation of the citation for the 2025 Nobel Prize in Physics: "for the discovery of macroscopic quantum mechanical tunnelling and energy quantisation in an electric circuit", understandable even to someone like me who ceased any formal study of physics at age 15 and has never studied quantum.) Gog the Mild (talk) 13:48, 7 November 2025 (UTC)

• "The lead section should be particularly understandable, but the advice to write one level down can be applied to the entire article." Er, so something should be the case, but it needn't be applied? Come on guys, you know how to write to FA level, where did this come from?
  • Reworded to 'but the advice to write one level down applies to the entire article'. I noticed it was weird, but hadn't been bold enough to change it before your nudge. —Femke 🐦 (talk) 08:41, 7 November 2025 (UTC)

LOL! You can imagine me reading this, remembering that a dozen top FA writers and reviewers have been all over it and wondering "What the hell happened here?" Pleased to hear that my nudge was helpful. Gog the Mild (talk) 13:48, 7 November 2025 (UTC)

• "Writing one level down also supports our goal to provide a tertiary source on the topic, which readers can use before they begin to read other sources about it." "our goal"? Would that be Wikipedia's goal? If so, I seem to have missed that one. Consider me to have hung a 'citation needed' on that, especially it being the singular goal of the encyclopedia.
  • I have not changed this sentence from before, but isn't this the definition of an encyclopedia, to be a tertiary source? —Femke 🐦 (talk) 08:41, 7 November 2025 (UTC)

Yep, the first bit is the synonymous definition. And "which readers can use before they begin to read other sources about it" is which part of Wikipedia's mission statement? Gog the Mild (talk) 13:48, 7 November 2025 (UTC)

"whereas a topic like Quantum chromodynamics should be described for a physics undergraduate." This is fundamentally impossible and inconsistent with the goal of the encyclopedia. It is also pointless: it will just be words that an undergrad can read but it won't be an article on quantum chromodynamics because the concepts are difficult for graduate students.

The first parts of quantum chromodynamics should summarize the most introductory sources we can find. Subsequence sections should summarized more complex or detailed sources. This is what Wikipedia can do. Johnjbarton (talk) 16:40, 10 November 2025 (UTC)

Suggest GoCER. Gog the Mild (talk) 23:03, 6 November 2025 (UTC)

Thanks for this, really useful. I would have liked to get one more round of feedback before an RfC, but my attempts to barter people with GA / FAC reviews hasn't been that fruitful. Most of your suggestions are for things that are in both versions of the guideline text, so I would agree with UC that they can be sorted out post RfC if we cannot find the right wording now. —Femke 🐦 (talk) 08:41, 7 November 2025 (UTC)

Note that I gave up at the end of Technical content on a WP:FIXLOOP basis. I have no reason to believe that I would not find issues - similar or different - if I were to continue. But this seems pointless when the guidance seems (to me) to be trying to do two incompatible things. I do not agree with you and UC that the only issues are tweaking the language which could be done post-RfC. I see two different philosophical approaches which the guidance attempts to hand wave around. If (once?) one approach were chosen, one may be able to comment usefully on the details. Gog the Mild (talk) 13:48, 7 November 2025 (UTC)

To clarify, the two philosophical approaches you see are

1. Make the article as accessible as possible (to the widest possible general audience).
2. Make the article accessible to the widest likely audience?

To me, they don't necessarily conflict, but are two partially overlapping conditions to writing accessibly.

Obviously the two don't always (necessarily) conflict. But guidelines like this are written to provide assistance with the hard cases, ie when they do overlap, and so those are the situations I have focused on. Gog the Mild (talk) 14:13, 9 November 2025 (UTC)

The first focuses more on what is possible, whereas the second one sets a minimum.

Sorry, I don't understand this. At first I thought you had cracked it, now I am not so sure. If the first is what we require, the second is redundant; the rest of the guidance can then focus on helping the editors of technical type articles meet his requirement. If the second is available as a fall back in tough cases then the first isn't accurate and should be struck as a potential source of conflict, misunderstanding and not actually helping editors understand that the second is the actual requirement. Gog the Mild (talk) 14:13, 9 November 2025 (UTC)

Imagine you have a topic that is basically only of interest at postgrad level, but it's possible to explain it in simple terms for a general audience. The first condition suggests we write it for this broad audience.

Now take a second topic also of interest to those at postgrad level, but now really difficult to explain in simple terms.

Sorry, but I do not accept this postulate. It may well be "really difficult to explain in simple terms", that does not mean that it can't be done, nor that it shouldn't be in Wikipedia articles. (I am thinking of my exercise time explanation of quantum tunnelling mentioned above as an example.) Gog the Mild (talk) 14:13, 9 November 2025 (UTC)

The second condition forces you to think about the likely audience, which will include those at undergrad level. Even if you might initially not think it possible to explain it to this audience, the second condition gives a minimum, so you'll have to get creative.

Which basically makes the first condition pointless. You are explicitly saying that when the going gets tough - ie the very situations in which editors turn to guidelines like these - the first can be jettisoned and the second used. Which - I am starting to repeat myself - makes me wonder why the first is ever mentioned at all. Gog the Mild (talk) 13:43, 9 November 2025 (UTC)

—Femke 🐦 (talk) 14:08, 8 November 2025 (UTC)

It occurs to me that you may think that I am being what in the UK we would call an arse. (Or something pithier.) So at the risk of unbecoming self-promotion I will mention that my opinion of what is possible in articles is based on copy editing more than 500,000 words of other peoples' articles at GoCE, carrying out more than 600 FAC reviews of other people's articles - some on thoroughly weird topics - and being responsible for summarising 120 FAs a year into 1,025 characters (including spaces) or fewer - knowing that they will get thoroughly picked over at or before the main page. Not to mention however many FACs I have been at the pointy end of deciding whether to promote or archive. Obviously none of this means that my opinion is the right one, but it may suggest that it carries some weight and that I have had more experience of applying this piece of guidance than many. Down at the sharp end I have found that the sort of distinction I am drawing above really matters. (In passing there is an expression "It is as plain as a pikestaff", meaning 'It is obvious'. Regardless, in several of my FAs I have defined pikestaff, including how practice differed from theory. :-) Eg see Battle of Winwick#Opposing forces#Infantry.) Gog the Mild (talk) 14:13, 9 November 2025 (UTC)

Not at all! This kind of critique is exactly what's needed if we want this guideline to be accepted and implemented widely. I think the first one is a bit of a exaggeration: we want the article to be accessible to the widest possible audience, which isn't always a general audience. Some maths articles simply cannot be explained to a general reader (not defending the status quo; from my experience doing a maths PhD, it is the topic area where the audience most often complains about Wikipedia being too difficult). So an alternative first sentence could be "Wikipedia should be written for the widest possible audience, and at least for the widest likely audience". —Femke 🐦 (talk) 08:20, 10 November 2025 (UTC)

• The proposal advices against use of passive voice, which contradicts MOS:PASSIVE: "The passive voice is inappropriate for some forms of writing, but it is widely used in encyclopedia articles, because [...]" (see here for recent discussion on this guideline). Olivaw-Daneel (talk) 23:37, 6 November 2025 (UTC)

• What about removing the word "Technical" from the guideline title, so it becomes Make articles understandable? That would solve a couple of issues: (a) some of the sections in the guideline apply to all articles (i.e. are not limited to Technical articles); and (b) WP does not yet have a guideline that covers "How to write a clear, understandable article". So why not use this renovation effort (which is off to a good start) to generalize the guideline to apply to all articles? It is not much of a stretch: virtually every article has "expert" or "technical" source material, so it should be a straightforward process to adapt the guideline to apply to all articles. Noleander (talk) 01:12, 7 November 2025 (UTC)

  In my opinion, that would defeat the purpose of this page, which is to provide a link when discussing (especially with relative newcomers) what kind of changes should be made to technical articles in particular. The needs of "technical" articles, i.e. those about topics which involve significant specialized knowledge, are different from the needs of other kinds of articles, and advice about "How to write a clear, understandable article" differs between the two. –jacobolus (t) 07:35, 7 November 2025 (UTC)

  I proposed this in Wikipedia_talk:MTAU#Should_all_articles_be_understandable?, and got enough pushback to not pursue this here with other more obvious changes to the guideline. And probably drop the idea altogether. If the guideline in rescoped in that way, it would still mostly be about technical articles, as understandability is typically not much of an issue outside of technical topics like engineering, humanities and science. The overlap would be in the use of plain language and the use of images. —Femke 🐦 (talk) 08:00, 7 November 2025 (UTC)

• I don't like the "For articles not of wide interest" qualifier, actually. It invites bikeshedding over how "wide" the "interest" of a particular article is. As I see it, "write one level down" is good advice to follow in general. It's the default presumption of how an article should be organized. Stepwise Continuous Dysfunction (talk) 22:49, 8 November 2025 (UTC)

  As far as I can tell "write one level down" conflicts with WP:Verify, "Wikipedia's content is determined by published information...". The section Write one level down says :

  • Consider the typical level where the topic is studied (for example, secondary, undergraduate, or postgraduate) and write the article for readers who are at the previous level.

  However by definition, the sources for an article will be at the typical level, not one level down. This one-level-down guideline is a recipe for original pedantic or tutorial content. What we want is Write at the introductory level then specify that this means the typical level where the topic is first introduced. Johnjbarton (talk) 03:37, 9 November 2025 (UTC)

  @Johnjbarton Wikipedia articles don't have to be written in precisely the style at precisely the level of the most common other works on some topic. We can bring in additional context, give glosses to jargon, add additional detail, add examples, describe the history of the subject, and so on. We shouldn't only discuss aspects of the topic of most interest to an expert doing cutting edge research, but also background knowledge that is obvious to an expert but not to a newcomer (e.g. a student or someone from a different technical field). Usually some essential description of a topic can be accessibly introduced to a less-prepared audience than serious students first encountering it as a topic of formal study. –jacobolus (t) 04:02, 9 November 2025 (UTC)

  I agree. We can deliberately choose to start articles by summarizing the most introductory sources first. (We already do that in the best articles). But we cannot "write one level down" from the most introductory sources and the guideline should not encourage attempts to do so. Verification is a essential. Johnjbarton (talk) 04:10, 9 November 2025 (UTC)

  As a concrete example, in Lexell's theorem I tried to make the lead section more accessible by glossing some terms and giving a bit of background in the (otherwise unnecessary) second paragraph:

  

  Orange triangles △ABC share a base AB and have the same area. The locus of their variable apex C is a small circle (dashed green) passing through the points antipodal to A and B.

  In spherical geometry, Lexell's theorem holds that every spherical triangle with the same surface area on a fixed base has its apex on a small circle, called Lexell's circle or Lexell's locus, passing through each of the two points antipodal to the two base vertices.

  A spherical triangle is a shape on a sphere consisting of three vertices (corner points) connected by three sides, each of which is part of a great circle (the analog on the sphere of a straight line in the plane, for example the equator and meridians of a globe). A small circle is any smaller circle on the sphere (for example the circles of latitude other than the equator). Any of the sides of a spherical triangle can be considered the base, and the opposite vertex is the corresponding apex. Two points on a sphere are antipodal if they are diametrically opposite, as far apart as possible. [...]

  You probably won't find much elaboration of this type directly in a paper or book chapter about the theorem (whose readers are assumed to know what spherical triangles, vertices, great circles, antipodal points, etc. mean), but you might find it in a source about more elementary aspects of spherical geometry. Readers who arrive at the article with no relevant background knowledge can still hopefully get a slight idea what the theorem is about by reading this second paragraph, jumping back and re-reading the first paragraph again, looking at the picture and its caption, and possibly clicking wikilinks on unfamiliar terms.

  This isn't by any means perfectly accessible, and even the beginning of the article is going to take nontrivial effort to make sense of for someone with no clue about the topic, but it is hopefully friendlier than the wall of inscrutable jargon some Wikipedia articles about technical topics begin with. –jacobolus (t) 04:54, 9 November 2025 (UTC)

  I think your writing is excellent but the introduction to Lexell's theorem does not match our guidelines in MOS:LEAD. It does not summarize the article and no sources to back up the nice text. It might be clear but it also might be WP:OR, I can't tell. This is exactly my point: if we advocate simplicity at the expense of verifiability readers and other editors have no way to know if it is correct or just simple. Johnjbarton (talk) 16:53, 9 November 2025 (UTC)

  MOS:LEAD gives 4 things the lead is supposed to do: "identify the topic, establish context, explain why the topic is notable, and summarize the most important points". Unpacking some key terminology is part of establishing context. A later section continues, "Where possible, avoid difficult-to-understand terminology, symbols, mathematical equations and formulas. Where uncommon terms are essential, they should be placed in context, linked, and briefly defined. The subject should be placed in a context familiar to a normal reader." –jacobolus (t) 20:20, 9 November 2025 (UTC)

  As long as even one source exists that treats a topic in a one-level-down way, we can write verifiable text that is one-level-down. For example, the opening chapter of a graduate textbook might give an outline and a sense of motivation for the subject matter which advanced undergraduates can handle. A calculus textbook might start with a chapter explaining what calculus is about in terms that students who have only done algebra and geometry can understand. It's really not that big a deal. Stepwise Continuous Dysfunction (talk) 06:20, 9 November 2025 (UTC)

  I agree, but what you are suggesting is not what I take away from the existing "Write one level down" section. We should be putting your advice about opening chapters in the section instead. Johnjbarton (talk) 16:47, 9 November 2025 (UTC)

  Advice about where to find sources is secondary to advice about what audience to target and what basic content to include in an article. I agree it could be useful to somewhere (whether in this guideline or elsewhere) include some tips for finding sources for elementary claims, but it's separate from this topic per se. –jacobolus (t) 20:27, 9 November 2025 (UTC)

  We don't even need one source treating the topic in a one-level-down way. Is this advice being thoroughly misunderstood?

  What "writing one level down" means is that if your source contains a sentence such as Methodological observation of the sociometrical behavior tendencies of prematurated isolates indicates that a causal relationship exists between groundward tropism and lachrimatory, or ‘crying’ behavior forms, then you should write what the source said, except that you should write it in your own words and in plain English, namely: Children cry when they fall down. Those two sentences say the same thing. The needlessly verbose source fully and directly supports the simpler sentence, so it meets all the requirements for the WP:V policy. Only one of those sentences is acceptable for a Wikipedia article.

  John, I've seen a couple of comments from you along these lines, and I want you to know that there is a substantial gap between Wikipedia:Close paraphrasing (which will get you banned) and WP:Original research (repeated incorrect accusations of which will get you blocked). Please check your understanding of what the community actually requires, because so far, every editor I've seen persist in the "If it's not a copyvio, it's unverifiable OR" view has ended up indef'd. This can be tricky for some people to grasp (especially people with a rigid thinking style), and I encourage you to make sure that you understand the difference between your personal preferences and the community's actual rules. (And if you don't – well, maybe stay out of those conversations.) WhatamIdoing (talk) 05:24, 10 November 2025 (UTC)

  (Please don't lecture me. Let's stick to discussing the topic.)

  Children cry when they fall down. is an incorrect summary of the preceding sentence you wrote. The previous sentence, while I assume it is a caricature of verbosity, describes a possible causal relationship based on observations. The summary states a fact. In a wikipedia article with a source, the one-level-down version should be replaced. Without a source it should be deleted. Johnjbarton (talk) 16:51, 10 November 2025 (UTC)

  The source I copied both sentences from says that those sentences mean the same thing. WhatamIdoing (talk) 18:02, 10 November 2025 (UTC)

  You should look for a better source. The red bit is not a sentence about child behavior, it is about "observations" and "causal relationships". I would challenge such a summary in a Talk page. Johnjbarton (talk) 18:12, 10 November 2025 (UTC)

  An editor is not a reliable source, and I think the community would disagree with your interpretation. WhatamIdoing (talk) 18:18, 10 November 2025 (UTC)

  Would you prefer Children often cry after they fall down ? ― Tosca-the-engineer (talk) 14:01, 12 November 2025 (UTC)

  This discussion is getting off the rails. The sentence about "Methodological observation..." is a parody of bad academic writing made up by humorist Dave Barry, not an extract from a real source.

  Here is a very important piece of advice: be sure to choose a major that does not involve Known Facts and Right Answers. This means you must not major in mathematics, physics, biology, or chemistry, because these subjects involve actual facts. [...] Scientists are extremely snotty about this.

  So you should major in subjects like English, philosophy, psychology, and sociology -- subjects in which nobody really understands what anybody else is talking about, and which involve virtually no actual facts. I attended classes in all these subjects, so I'll give you a quick overview of each: [...]

  SOCIOLOGY: For sheer lack of intelligibility, sociology is far and away the number one subject. I sat through hundreds of hours of sociology courses, and read gobs of sociology writing, and I never once heard or read a coherent statement. This is because sociologists want to be considered scientists, so they spend most of their time translating simple, obvious observations into scientific-sounding code. If you plan to major in sociology, you'll have to learn to do the same thing. For example, suppose you have observed that children cry when they fall down. You should write: "Methodological observation of the sociometrical behavior tendencies of prematurated isolates indicates that a casual relationship exists between groundward tropism and lachrimatory, or 'crying,' behavior forms." If you can keep this up for fifty or sixty pages, you will get a large government grant.

  We shouldn't be trying to subject this sentence to serious analysis. –jacobolus (t) 20:04, 12 November 2025 (UTC)

  User:Stepwise Continuous Dysfunction: one alternative wording to "for articles not of wide interest" is to link ONEDOWN more explicitly to the nutshell instead. That is: onedown as an explanation of "widest likely audience". When a topic is typically treated at postgrad level, there will be undergrads being curious too. Would you see that as an improvement? I personally see two reasons for ONEDOWN. (1) people overestimate their readers, so tell them to write for a less knowledgeable audience might reduce that bias and (2) the above: there will be people in the audience that are less knowledgeable than the average reader. —Femke 🐦 (talk) 07:58, 10 November 2025 (UTC)

  I kind of like that. Stepwise Continuous Dysfunction (talk) 04:35, 11 November 2025 (UTC)

• The proposed guideline, as currently written, falls down where it is needed most. It provides examples for the little things, like saying house sparrow instead of Passer domesticus, but when it comes to the less obvious challenges, the problems that are more Wikipedia-specific and that require more thought in each case to resolve, it offers basically nothing. "Put easier content up front", we're told. OK, what's an article that does that? It says A good example of a background section can be found in Special relativity § Background. I'd disagree that that's a "good" example at all. Half of it isn't even background. It gives one bullet-point list of terms that might be considered background or prerequisite stuff, and then it goes haring off into trying to cover all of special relativity itself. Even in that list, there are phrases which aren't "background", like saying an "event" is "a generalization of a point in geometrical space". If you don't already know special relativity, this will be opaque to you. At best, that section is a glossary, not background. Likewise, the guideline says, the mathematical concept of the Klein bottle is first explained in everyday terms, before a formal definition is given. The Klein bottle article calls it a "non-orientable surface" before giving an informal description! Overall, the proposed guideline feels more like it was written to solidify a particular ideology about how Wikipedia should do things, rather than engaging with specific successes and failures of technical articles as they actually exist. Stepwise Continuous Dysfunction (talk) 23:13, 8 November 2025 (UTC)

  Try reading Special relativity without Special relativity § Background. Now it is a complete loss.

  The fundamental problem here is that a topic like special relativity requires entire books to explain. It is completely impractical to have an encyclopedia article on special relativity that covers its essential elements at one level below its typical introduction. We cannot succeed. In an wiki encyclopedia we can provide links for readers to come up to speed, which is what the Background section attempts.

  Could Special relativity § Background be better? Of course. Would a five page expansion of that section be better? No. Brevity is vital for an effective encyclopedia. Johnjbarton (talk) 03:49, 9 November 2025 (UTC)

  Ditto for other fields, history, ficiton, etc. Random niche historical topic like nihil novi, in its main body, is also pretty "technical" for folks not versed in history of that time and place. Even more so when we deal with stuff that has no estabilished English name. From: Wojsko kwarciane: "Wojsko kwarciane was formed from earlier obrona potoczna units" :P Tell me this is less technical than a random sentence from special relativity :P _{Piotr Konieczny aka Prokonsul Piotrus| reply here} 05:18, 9 November 2025 (UTC)

  Yes, wojsko kwarciane and obrona potoczna are dramatically less technical as topics than special relativity is. They are just two names for the Polish army in 15th–16th centuries. Understanding the basic concept doesn't require any special effort or training, and the only difficulty involved is that their names are Polish rather than English words. Understanding their full nature and context requires some learning about Polish history, but a typical 15-year-old student could make basic sense of it in a matter of hours (as compared to requiring several demanding year-long classes in mathematics and physics to cover the prerequisites). Moreover, special relativity is a central topic about which we would expect to have additional effort put into accessibility (a reasonable comparison might be with Military of the Polish–Lithuanian Commonwealth); if we start delving into more detailed articles like Sagnac effect, Terrell rotation, Rindler coordinates, and so on, we expect to find material that is even more technical, based on an assumption that readers are already familiar with the basic content of special relativity. –jacobolus (t) 05:49, 9 November 2025 (UTC)

  I think Special relativity without the "Background" section would be an improvement. The following section, which the "Background" is supposed to prepare the reader for, has language like an observer on a train sees natural phenomena on that train that look the same whether the train is moving or not. But the "Background" section says things like The spacetime interval is an invariant between inertial frames, demonstrating the physical unity of spacetime. This is the wrong damn way around. But the salient point for this discussion is that because Special relativity § Background is lousily written, it's a bad example for this guideline to point to. Either fix Special relativity § Background or find a better example.

  Because the proposed guideline provides either no examples or bad examples for all the hard stuff, it's not ready for prime time. Stepwise Continuous Dysfunction (talk) 06:12, 9 November 2025 (UTC)

  Point taken on that section being overly difficult. I can't access my textbooks on the topic, but will see if I can rewrite this with sources online, unless others are aware of another better background section. —Femke 🐦 (talk) 07:54, 9 November 2025 (UTC)

  The section is now rewritten, feedback welcome. —Femke 🐦 (talk) 09:45, 9 November 2025 (UTC)

  Rewritten where? _{Piotr Konieczny aka Prokonsul Piotrus| reply here} 11:48, 9 November 2025 (UTC)

  At Special relativity#Terminology. It's been tricky to find good examples for each principle and tip in the guidelines, and here I'd only read the initial bit of the background section before adding it to the guideline. Easier to fix the example than to find another one. —Femke 🐦 (talk) 11:53, 9 November 2025 (UTC)

  I think that the lack of existing better examples is not an accident, but rather is evidence that some goals of the guideline are not obtainable in the Wikipedia format. We simply cannot provide a one-level-down description of complex concepts here. Rather than investing energy in an unattainable goal we should aim for simpler guidelines. Johnjbarton (talk) 16:42, 9 November 2025 (UTC)

  I've seen a lot of fantastic articles that nailed the ONEDOWN element. When I review articles at FAC, and I request that people rewrite portions of their noms to comply with this guideline, they typically come up with amazing prose that really explains what they're trying to explain. I've rarely reviewed an article where people were unable to explain the topic after nudges. —Femke 🐦 (talk) 16:49, 9 November 2025 (UTC)

  Well I've seen zero. One example would be a start. Johnjbarton (talk) 16:54, 9 November 2025 (UTC)

Weell, I mention above "there is an expression "It is as plain as a pikestaff", meaning 'It is obvious'. Regardless, in several of my FAs I have defined pikestaff, including how practice differed from theory." Thinking on't, much the same applies to many things which could be considered technical, like optimising the use of slow match; or why sailing times between ports in the 14th century were hugely uncertain - including up to three months to simply get out of harbour; or so very much about feudal obligations. None of these involve quantum tunnelling, but the last is arguably as tricky to write comprehensively about for a non-specialist modern audience. Gog the Mild (talk) 19:40, 9 November 2025 (UTC)

I'm struggling to understand your reply. Are you suggesting that Pike (weapon) and slow match are good examples of understandable technical articles written "one-level-down"? If so I am unconvinced, they do not read as one-level-down to me. Johnjbarton (talk) 19:55, 9 November 2025 (UTC)

No, the claim is that it is not obvious to Wikipedia readers what a pikestaff is (despite the 16th-century idiom to the contrary). Therefore, when the concept appears in some article about soldiers, battles, fortifications, or whatever, it is helpful to gloss the term pikestaff and provide explanation about how pikes were used in warfare. –jacobolus (t) 20:36, 9 November 2025 (UTC)

As for examples: Most of the technical articles I write have a general audience (medical conditions, key climate and energy articles). There's one which does not: climate sensitivity. That topic is usually covered at undergraduate level, but should be understandable for an upper secondary school audience. For instance, before explaining how you can derive climate sensitivity from climate models, it explains how climate models work. This has meant bringing in some general climate sources, rather than sources specific to climate models, but that's fine as long as it's not excessive and no WP:SYNTH takes place. Most of the time, it's just paraphrasing academic sources into plain English. —Femke 🐦 (talk) 07:20, 10 November 2025 (UTC)

I clearly won't be able to convince you. I think climate sensitivity is a completely normal, well-written article but it is not "one level down". The first section "Fundamentals" introduces jargon. The second section starts with The radiative forcing caused by a doubling of atmospheric CO2 levels (from the pre-industrial 280 ppm) is approximately 3.7 watts per square meter (W/m2). This is what we do. It's wonderful, let's not beat ourselves up. Johnjbarton (talk) 17:10, 10 November 2025 (UTC)

What makes you think that upper secondary school students can't learn a few words of jargon? At school, they teach you jargon all the time. In the article, the amount of jargon is quite limited, and there's plenty of space teaching jargon before it's used in further sections. —Femke 🐦 (talk) 17:17, 10 November 2025 (UTC)

Thank you for that clear explanation. I agree that unusual words should be avoided. When possible we should describe concepts early in an article without using the shorthand jargon or idioms. Later sections should introduce and explain these terms. The deeper parts of the article can use the terms directly. Johnjbarton (talk) 17:16, 10 November 2025 (UTC)

Klein bottle now no longer has jargon in the first two sentences. —Femke 🐦 (talk) 07:20, 10 November 2025 (UTC)

Klein bottle doesn't define the term Klein bottle anywhere in the lead section, which seems suboptimal to me. Overall the article (including the lead section) seems quite underdeveloped. –jacobolus (t) 07:54, 10 November 2025 (UTC)

What would you give as a definition? I think the second sentence ("a one-sided surface which, if traveled upon, could be followed back to the point of origin while flipping the traveler upside down") works pretty well as a definition. WhatamIdoing (talk) 18:14, 10 November 2025 (UTC)

I think I'd mention something like a Klein bottle being constructible as a cylindrical tube whose top is connected to its bottom after being flipped around (I'm sure with effort someone can come up with a moderately clear phrasing). The current version just tells us which broader class of objects the Klein bottle is a specific example of, which is not the same as defining it. The most basic example of a surface satisfying the same criterion is the real projective plane (e.g. immersed as Boy's surface).

Aside: it might be worth mentioning somewhere that the original German name was "Klein surface", nothing to do with bottles per se, but translators got confused between flasche and fläche, or perhaps made a little joke, and later people found the "bottle" name to be cuter. –jacobolus (t) 18:39, 10 November 2025 (UTC)

I think mentioning the flasche–fläche translation thing is a good idea; thinking of it as a surface makes the concept much clearer.

Regarding definitions, sarah-marie belcastro described a Klein bottle as: an abstract, infinitely thin mathematical surface, formed in such a way that its inside is contiguous with its outside. That is, if it were thickened enough have an inner skin separate from its outer skin, you could run a finger along the surface from any point on the outside to the corresponding point on the inside. The next figure in the article is a diagram showing the transformation of a tube into a Klein bottle.

Link to the article On mobile, you may need to tap the ⊕ symbol to see the article figure captions. ― Tosca-the-engineer (talk) 11:39, 14 November 2025 (UTC)

This is conceptually the same as our current lead; it describes one property but doesn't specifically define the surface.

According to one source found in a web search, Klein's original description (in translation) is: a "certain unbounded double surface" which "can be visualized by inverting a piece of a rubber tube and by letting it pass through itself so that outside and inside meet." A different translation has: "tucking a rubber hose, making it penetrate itself, and then smoothly gluing the two ends together". I'm not sure how clear that would be to readers though. –jacobolus (t) 20:23, 14 November 2025 (UTC)

Question 2: retiring the introductory articles

Should Introduction to ... articles be deprecated?

That is: should the section on introductory articles be deleted from the guideline, in addition to the sentence in WP:CFORK?

Survey

• Weak support. We're talking about 11 articles here, so it's only a small fraction of our technical articles. We have limited maintenance capacity in the community, so my preference is to merge the two, making sure that the main articles are accessible to a wide audience. The introduction articles usually have lower pageviews than the main articles, despite there likely being a larger audience interested in getting a good introduction to a topic. By merging these articles, we make well-explained content more readily available. Weak support as I'm not quite sure if these big merges are the best use of community time, and because I'm afraid that people will delete the articles rather than appropriately merging. —Femke 🐦 (talk) 11:45, 9 November 2025 (UTC)
• Deleted IFF we move that content to another page and update the redirect and the WP:INTROTO shortcut to point somewhere rather than at this page which will have no relevant content anymore. Ptherwise this will have to grandfathered in (as much as I'd like to simply declare these articles a bad idea and have them merged/blanked as forks - but that's another RfC in making; this issue should not derail the above, reasonable improvements to this page that seem to be passing anyway). --_{Piotr Konieczny aka Prokonsul Piotrus| reply here} 11:50, 9 November 2025 (UTC)
• Support Abaciscus (talk) 15:04, 9 November 2025 (UTC)

  ...and your reasons are? Graham Beards (talk) 15:23, 9 November 2025 (UTC)

• I think we should keep the "Introduction to" articles, and specifically, I think that they shouldn't be handled as a one-size-fits-all or as a systematic series of merge proposals. They're in okay shape now, and they have readers. I recommend that we leave them alone until at least one of those two things stops being true. WhatamIdoing (talk) 20:50, 9 November 2025 (UTC)
• Oppose While I don't neceessarily like the concept of "Introduction to" articles on Wikipedia, I don't know of a better way of doing things for articles that are of interested to both technical audiances and to lay people, which is the ones usually covered by this category. If anything I would extend the number of "Introduction to" articles. Writing "One level down" is always a bit tricky since it depends on what level you're writing in the first place. For example, M-theory and string theory both pretty nice articles, yet they actually fail to be one-level-down in that they are not one-level down from string theoriests, and so are completely/largely useless for anyone needing to actually learn that topic. They currently actually serve the role of "Introduction to" type articles and are only useful for a general audiance. Compare it to other articles in the same area like RNS formalism which I would say is written one-level down, in that they readable/useful for people learning that topic (late undergrad/postgrad in this case) and acts as a useful encyclopedic/reference article. I could see a push to rename the M-theory and string theory articles as "Intro to" ones since they are good articles, so would be a shame to completely replace them/merge them with a technical article, thus loosing a lot of their content.

I could see that topics with a significant general audiance that correspond to a Wikipedia category, like string theory, have an overly simple article, but then the more specific topics within that category are on the correct technical level, like RNS formalism, since those will in general not be read by everyone, so they conform to one-level-down. Under that philosophy "Intro to" articles would be unecessary. Downside is a two-tiered system for articles where some are no longer one-level-down but like 3-levels down. It is also the case only with some articles like string/M theory. Quantum field theory (a bit of a mess imo of an article) is not friendly to the general audaince, but thats what makes it useful for people actually trying to learn QFT in that it is one-level-down for them. An intro to QFT would actually be useful in this case. OpenScience709 (talk) 21:42, 9 November 2025 (UTC)

One of the key problems with trying to merge intro articles with the main one is that either you have to restate everything twice, one in simple language everyone can understand and once from a one-level-down perspective (making articles repetitive and long), or else you pick one and then the other one is left out, which isn't great either. OpenScience709 (talk) 21:45, 9 November 2025 (UTC)

A side comment on the possibility of expanding Intro articles out, I would argue that usually highly technical Wikipedia topics that correspond to entire Categories with a sufficient number of pages, usually deserve introduction to articles. Like Quantum Field Theory, Quantum gravity, String Theory, etc. (As stated earlier, some of the current versions already effectively act as such, so are useless for people learning the topic so would be useful to have more technical articles on them) In those cases there clearly is enough material to cover a lot of it at a general audiance level, and it would also make sense structurally in (at least my) philosophy of the structure of Wikipedia. Expanding out their number would also make people more aware of them, so could drive up readership. The current lack of readership may be due to their limited number in the first place, so people are unaware that they exist. OpenScience709 (talk) 21:53, 9 November 2025 (UTC)

• Strong oppose, it's a good idea, it has worked and does work, and the advice on introductory articles should be retained. SandyGeorgia (Talk) 00:43, 10 November 2025 (UTC)
• Oppose – I don't think a good enough rationale for eliminating "introduction" articles has been provided, nor has much apparent thought gone into how they would be merged, in practice. I don't think this is the intent, but it comes across as a few editors who don't like the introduction articles (and maybe haven't really thought much about the topics they cover) trying to force other volunteers to abide by their personal preferences without being willing to do the work personally. If someone wanted to see such a step happen, the way to accomplish it would be to make at least a partial draft (e.g. in user or article talk namespace) of a merger of one of the introduction articles and the corresponding "non-introduction" article, and then try to convince the other editors working on those two articles that the merged article was a better result than the two articles separately and join in the effort to carry through the merger. This should be done one article at a time, and if it works out, they could recruit other interested editors to try the same with the various other introduction articles. Once those were mostly or entirely merged, guidance about them could be removed or rewritten. I don't expect this to happen though, as it would take significant amounts of effort. –jacobolus (t) 00:53, 10 November 2025 (UTC)
• Oppose I'm just not seeing the case against advising people to write "Introduction to..." articles when the topic is hard enough to call for one. Just because they might get fewer views doesn't make them a bad idea. Stepwise Continuous Dysfunction (talk) 04:40, 11 November 2025 (UTC)
• Strong Oppose. I opposed this on the first RfC and I am joining the chorus on opposing it again. There are very good reasons why at universities we have "Introduction" courses and then more advanced ones. It is good pedagogy, and similarly it is good encyclopedia design. Taking the obvious example of quantum mechanics, we should have an intro article at a high-school level, plus other articles at the higher-level undergrad/grad. Mixing them creates monsters that nobody will read, will confuse the novice and bore the more advanced reader.

An additional and important point: the style for an intro article and an advanced one are very different. An intro has to gently explain everything, and an advanced one should assume some background. I would say that it is considerably harder to write a good intro article, just as it is often much harder to teach intro classes than advanced ones.Ldm1954 (talk) 14:32, 11 November 2025 (UTC)

• Oppose – It is impossible for me to do anything other than oppose this proposal, because no rationale for deprecation has been provided. It seems strange to suggest the deletion (or merging) of articles without any justification... Yours, &c. RGloucester — ☎ 05:28, 13 November 2025 (UTC)
• Oppose – I don't see any strong rationale for this proposal. MichaelMaggs (talk) 08:50, 13 November 2025 (UTC)

Discussion Question 2

• This page is a wreck. The question is phrased as if the articles themselves are to be deleted. What is the proposal? SandyGeorgia (Talk) 13:52, 9 November 2025 (UTC)

  My view is that they should be merged into the main article, eventually, as the exception in CFORK for their existence would be removed. @Piotrus argued most strongly for this in the workshop. Is that also what you would like to see? There's valuable content in there, so deletion doesn't sound like a good idea. —Femke 🐦 (talk) 14:13, 9 November 2025 (UTC)

  I just want to know what I'm opining on, and neither the RFC wording, nor the talk page message, are clear. If we are trying to remove Introduction to articles entirely, then I am strongly opposed ... and need to spend much more time on this (lengthy) page trying to understand what is going on here. SandyGeorgia (Talk) 14:51, 9 November 2025 (UTC)

• Impressive work, Femke! Have you consulted the Simplified Technical English manual by any chance? Szmenderowiecki (talk · contribs) 12:00, 13 November 2025 (UTC)

  Simplified Technical English seems like a poor fit for an encyclopedia. It's a strict and very stilted subset of English designed for maintenance manuals so that non-English-speaking mechanics can use them to fix broken machines with fewer misunderstandings. –jacobolus (t) 19:16, 13 November 2025 (UTC)

  I did not use that work, no. The advice there corresponds roughly with those from the NHS, NIH, UK governemnt that I did look at, even though it is even more detailed and in some cases, strict. Other external sources I based the rewrite on were science communication books such as Escape from the Ivory Tower and Explaining Research. I further scoured WikiProjects for advice. —Femke 🐦 (talk) 07:53, 14 November 2025 (UTC)

Related: meta discussion about Simple

See meta:Requests for comment/The state of Simple English Wikipedia. _{Piotr Konieczny aka Prokonsul Piotrus| reply here} 05:10, 9 November 2025 (UTC)

Confusing

I was directed to this page by this message ("discussion on retiring introductory articles"), which sounds like a proposal to remove Introductory articles. Coming to this page, I found talk sections hadn't been archived for years and a clear link to the introductory proposal couldn't be found.

Could someone clarify and address the talk page messages if they are indeed incorrect? SandyGeorgia (Talk) 14:02, 9 November 2025 (UTC)

@SandyGeorgia Perhaps you mean Wikipedia_talk:Make_technical_articles_understandable#Discussion and the discussion(s) below it. _{Piotr Konieczny aka Prokonsul Piotrus| reply here} 14:49, 9 November 2025 (UTC)

Thx Piotr I'll catch up on that this afternoon ... when I came to the page, there were multiple discussion links and a huge page that hadn't been archived for years -- someone should tend to the housekeeping before launching such a significant RFC. Is there a summary anywhere of what the basic changes are? Are we or are we not trying to eliminate "Introduction to" articles? SandyGeorgia (Talk) 14:53, 9 November 2025 (UTC)

PS -- what a sad way to derail an RFC -- it appears there is an effort to simultaneously advocate for the deletion of content unrelated to the guideline. These concepts aren't mutually exclusive. SandyGeorgia (Talk) 15:00, 9 November 2025 (UTC)

Hi @SandyGeorgia, apologies for the mess. I think I posted a few months back that they should be separate RfC questions. And then I forgot about that aspect of the changes and my intention to separate these out.

Most changes in the workshopped text are describing good practice, introducing examples, and giving guidance on how to avoid common pitfalls

• In the section on limiting jargon, one strategy has been added to give hints in the surrounding text that allow people to deduce what the jargon means. For instance, for jargon you've explained in a previous section where you need to jog someone's memory.
• It talks about how using academic sources only may lead to overly complicated text, as editors emulate this style, and points to using textbooks to find how to explain things are a more appropriate level
• It includes more focus on using clear English, such as removing redundancy (WP:REDEX), so that people don't have to struggle with difficult prose while learning new concepts.
• It explains a bit more how to design technical images
• It includes the principle that it's tough to write understandably on your own (as you tend to overestimate others when you learn about a topic), and that seeking feedback is valuable.

I've also tried to make the guideline easier to read, even though there are people arguing we should go much further in that regard. —Femke 🐦 (talk) 15:51, 9 November 2025 (UTC)

Thx Femke ... I have to digest walls of text here before forming an opinion, but from what I've been able to glean so far, Gog the Mild is summarizing the best (feels like the workshopping wasn't complete). SandyGeorgia (Talk) 19:57, 9 November 2025 (UTC)

Allright, I caught up. @Femke and Jens Lallensack: enlisting Colin would be the fastest route to making this page shine. He's the editor who best knows the pitfalls, how to write a tight guideline, and how to write technical articles. SandyGeorgia (Talk) 01:59, 10 November 2025 (UTC)

Alternative to workshop "Write one level down"

In the discussion above I critiqued the concept of "write one level down" as inappropriate primarily because verifiablity is critical to Wikipedia. We summarize sources and sources are "at level". Here I propose an alternative, based mainly on great feedback to my complaints above.

Summarize introductory sources first

To increase understandability, summarize introductory secondary sources in the first sections of the article. Context discussed in these introductory sources should be summarized, with wikilinks for readers who seek more background. The subject should be placed in a context familiar to a normal reader. Describe concepts early in an article without using the shorthand jargon or idioms. Later sections should introduce and explain these terms. The deeper parts of the article can use the terms directly. The lead section should be particularly understandable, but all parts of the article should summarize technical content clearly. Our goal is to provide a tertiary source on the topic, which readers can use before they begin to read other sources about it.

My purpose in making this proposal is to focus on the achievable goals of the one-level-down concept without setting up a conflict with verifiability or encouraging attempts to explain complex topics independent of summarizing sources. I'm not asking that it be included, it is just a suggestion. Johnjbarton (talk) 18:40, 10 November 2025 (UTC)

You seem to be the only one who sees a conflict between ONEDOWN and verifiability. With some topics (medical stuff), and with phone reading on the rise, I don't think we want to set articles up with such a easy-to-hard structure. In fact, that's one of the key things I changed as dated from the old guidelines. People are quite likely to start in the middle of an article; I don't think there is a 'deeper' part of an article.

Note that when you summarise a source, you usually cut out the details that makes it easier to understand. So it's not even like you preserve the difficulty of the original source. —Femke 🐦 (talk) 18:51, 10 November 2025 (UTC)

There is undoubtedly a tension between this guideline and Wikipedia's verifiability policy, and I feel like a certain amount of verifiability is often sacrificed in the name of accessibility. For example, deep theorems of functional analysis are often never presented in a way that can even be understood by typical undergraduate math majors, but we try anyway. Tito Omburo (talk) 20:20, 10 November 2025 (UTC)

This is a very key headache and point:

I feel like a certain amount of verifiability is often sacrificed in the name of accessibility.

I ran into that on Field propulsion, that I'm slowly chewing through. This part under Field propulsion#Definition:

By interacting with such external reservoirs, a spacecraft could in principle "push off" the surrounding medium, converting environmental energy or momentum into acceleration.

Bolded bit, to sum up the 'how' in a clear and easy to understand way. That took a lot of headache to come up with a wording that would fit but is a "dumbed down" and as close to WP:V phrasing as I could get. I did a better job up front on Mosaic effect, but my initial writing on field is my older stuff (it took much longer).

Is there any essay or policy that gets into this tension? It has to be common? — Very Polite Person (talk/contribs) 03:21, 11 November 2025 (UTC)

Unfortunately, it seems largely to be papered-over. Someone writes a lucid and clear explanation of something, and it remains in spite of perhaps violating the letter of WP:V, its exact content only supported in a very general way by sources, but often than content is actually rather good, and earns praise even from other editors. It's understandable we don't want a policy or guideline that says "come up with examples that illustrate a topic, even if that topic is only covered in sources that usually require a PhD in a specific sub-field of a discipline to understand", because that opens the floodgates to lots of bad things too. (Honestly, making it WP:GOOD should be the important thing, lol.) One has to walk a careful line in such cases: not straying too far from policies, while making things accessible to as many readers as possible (especially the earlier sections). I personally think a hard line on WP:V would be acceptable, but this guideline would need to be completely rewritten in that case, and I think this balance kind of "works" in spite of its manifest deficiency in policy. Tito Omburo (talk) 22:04, 12 November 2025 (UTC)

To borrow from a gaming analogy...

• Lede: storyteller mode
• Background/Details/Definition type sections, especially first paragraphs: easy mode
• Later paragraphs of early sections: normal mode
• Deeper sections of the article progressively scale from hard mode to "good luck with that" mode

Sort of this sort of scaling? — Very Polite Person (talk/contribs) 03:11, 11 November 2025 (UTC)

• • I'm not sure why we would want to include any text as a 'good luck with that'. That doesn't serve our readers. And the phrase 'dumbing down' equates simplicity with stupidity, rather than recognizing that intelligent people also benefit if we explain things clearly and intuitively. —Femke 🐦 (talk) 08:04, 11 November 2025 (UTC)

    I agree with you on the phrase "dumbing down". We should never dumb down. We should try to make things as understandable as possible.

    That said, there should be no upper limit to the difficulty of material that can be presented in Wikipedia, and some of that will indeed be useless to people without the necessary background, which will be most people. It's not true that that doesn't serve our readers. It serves them by collecting the information in a reference work (this is important: Wikipedia is a reference work, not a teaching tool) that they can access if and when they acquire the necessary background. --Trovatore (talk) 19:37, 12 November 2025 (UTC)

    Maybe we don't disagree too much here.

    When readers come to Wikipedia, they often come to learn more about a topic. People use Wikipedia as a teaching tool. While it will never be as effective as a textbook with exercises, that doesn't mean our readers won't try. And I believe we should accomodate that. I wonder if the reason our maths articles are so tough to read for maths students and researchers, is an overcorrection away from textbook style explanations.

    We don't have that much hard data on the range of needs our maths readers have. I recently opened a wish for experienced users to ask questions from readers ([6]), which might help us get hard data on this. —Femke 🐦 (talk) 20:21, 12 November 2025 (UTC)

    Wikipedia is and should be a valuable resource for self-teaching. It should not try to actively teach. Part of the problem with text written to try to teach the reader is that it's likely to fail NPOV, by presenting the material in the way the writer thinks is important.

    One reason that readers are shocked when they try to read our math articles is that they have the wrong expectations about how hard it is to read math. A mathematician is not surprised if they look up an argument and find that it takes a full day to read the first two pages. That's just kind of normal. They don't feel offended that it's written over their head; they just have to work harder. There isn't really any way around that. Hand-holding reaches a point of diminishing returns pretty quickly, annoying those who have the background to read the material without being of much help to those that don't. --Trovatore (talk) 20:31, 12 November 2025 (UTC)

    I did my PhD in a maths department. And those people were surprised at how difficult maths on Wikipedia is. It's not outsiders who have only done high school or even undergraduate mathematics. —Femke 🐦 (talk) 20:46, 12 November 2025 (UTC)

    I don't really buy this explanation. There's a big difference in written clarity between the best and worst math articles here, or more generally between the best and worst mathematical writing in books and papers. Plenty of our articles are bad not because they're describing something inherently complex or obscure, per se, but because they omit basic information, have no or confusing illustrations, aren't structured coherently, jump from topic to topic or equation to equation without connective prose, wrap relatively straightforward ideas in layers of exclusionary/obfuscatory abstraction, or present an idiosyncratic original approach of the editors who originally wrote them.

    Wikipedia has some inherent challenges compared to a textbook: we can't give a careful sequence of topics aimed at a specific audience with known background, with each chapter able to assume the content of previous chapters, and an assumption that readers will spend months of effort on the topic. Because each article is to a certain extent a self-contained document, and our audience is very broad, each one must repeat more context than would be included in either a textbook chapter or a research paper. But on the other hand, this can be an advantage as well: we can give each concept (term, theorem, well-known example, person, book) its own separate article and unpack it in detail with more context than would be possible in a textbook, making deeper information much easier to find than it would be if the reader had to hunt it down in an obscure expository paper.

    In my opinion, the primary thing stopping us is coordination/collaboration, manpower, and time, rather than inherent limitations of the medium or subject. If we could magically recruit the author of the best survey paper about each topic to write the corresponding Wikipedia article and chip in a bit on articles about adjacent or prerequisite topics, supported by a team of excellent illustrators and research assistants and a mentor versed in Wikipedia norms, I expect we would generally end up with excellent results. –jacobolus (t) 00:24, 13 November 2025 (UTC)

I disagree with the basic premise that sources are necessarily "at level". ONEDOWN is an emphatic way of saying that people who don't already know a subject should be able to get something from the article about it; many pedagogical references (the ones that aren't worthless) do the same thing. Many textbooks give "previews" of material that is taught more systematically in later courses. For example, first-year university physics texts called things like College Physics or University Physics are apt to have a chapter on thermodynamics, on special relativity, and/or a chapter on quantum mechanics. All of these would get a whole semester each later in a physics degree, but we can outline them in a respectable way using the first-year books, no verifiability problems at all. And sometimes, writing one-level-down just means unpacking things that are said more tersely in an advanced course, because the students in the advanced course are presumed to have more background knowledge. Stepwise Continuous Dysfunction (talk) 05:04, 12 November 2025 (UTC)

I realise that I'm rather late to the conversation (*checks timestamps* uh, almost a year late...), but I hardly ever bother to look at wikipedia for understanding maths or physics concepts, because the explanations are so rarely helpful. They often remind me of the Sylvanus P. Thompson quote from Calculus Made Easy:

Some calculus-tricks are quite easy. Some are enormously difficult. The fools who write the textbooks of advanced mathematics — and they are mostly clever fools — seldom take the trouble to show you how easy the easy calculations are. On the contrary, they seem to desire to impress you with their tremendous cleverness by going about it in the most difficult way.

— Preceding unsigned comment added by Tosca-the-engineer (talk • contribs) 14:05, 12 November 2025 (UTC)

Making things difficult can be a problem, but in my experience a bigger problem is the editors who indiscriminately slap {{technical}} tags on any article that should be technical, arguing that the article should instead be made accessible to a general audience by eliminating all technical content. WP:ONEDOWN is important as clarification for the level to set, heads off problematic tagging, prevents the inappropriate removal of important but technical content, and makes it less ambiguous whether an article is or is not too technical. —David Eppstein (talk) 23:26, 15 November 2025 (UTC)

Some things actually can be written one or more levels down. Especially the lede. Clearing technical tags on math articles has been somewhat illuminating in this regard. I hate the tag too, but there is a minimal level of work that can be done to remove it, even from extremely technical articles. Technical articles obviously should be technical, but the basic rubric is that the first sentences of the lede especially should be legible to someone with a good education who arrives at the article via the "Random article" feature. Tito Omburo (talk) 23:26, 19 November 2025 (UTC)

I'm really curious how you would do that for, say, Stone–Čech compactification. I can't think of anything that "someone with a good education" could understand about it that isn't so general as to be essentially unrelated to the topic. --Trovatore (talk) 23:53, 19 November 2025 (UTC)

Something roughly like this: Suppose one has a space, such as a collection of points, and it is desired to "complete" this space to include all possible idealized limits, including ones that do not come from ordinary sequences. The Stone-Cech compactification is the most powerful (so-called "universal") way to do this. The Stone-Cech compactification of a space $X$, denoted $\beta X$ has the property that each bounded continuous function on $X$ extends uniquely to a continuous function on $\beta X$, and this correspondence characterizes the Stone-Cech compactification. For many comparatively simple topological spaces, such as infinite discrete spaces, the Stone-Cech compactification cannot be constructed explicitly, requiring the axiom of choice. Tito Omburo (talk) 13:00, 20 November 2025 (UTC)

OK, so you're aware I hope that a typical "person with a good education":

• Doesn't know what a topological space is
• Is going to be confused by the first "one has a space". What's a space? I know about space. What does it mean to have space?
• Has no idea what you mean by "all possible idealized limits" (actually I'm not sure I know what you mean by that; are you talking about nets maybe?)

I don't see the value in this, to be honest. You aren't really giving any intuition to the average "well-educated" reader. You're making the reader who has background wade through stuff they already know. In the meantime you're making questionable claims like this compactification being the "most powerful", whatever that means. --Trovatore (talk) 20:40, 20 November 2025 (UTC)

This is kind of an unexpected reply. I thought it would be critiqued for reasons of lack of rigor, not because it fails to convey the main idea in a way more suitable to a well-educated reader. In any case, I think it's likely my version is much more likely to be understood than what was there before. As to the "value", maybe the current guideline has no "value" for highly technical articles like the one under discussion. That's a view that I am open to, and would readily endorse if there were anything like consensus for it. Anyway, I've polished my version a bit (without seeing your reply). Let's put it to the peanut gallery: original version versus new version? Tito Omburo (talk) 21:34, 20 November 2025 (UTC)

I have some quibbles but it does look better now (and also substantially better than your first try). However I'm still not convinced that a typical "someone with a good education" can get much out of it. I still doubt that's really possible. But yes, now it should be much easier for, say, a third-year undergrad math major to start reading it, and that is a good thing. --Trovatore (talk) 23:46, 20 November 2025 (UTC)

From the peanut gallery:

What does it mean to "enlarge a space"? What is the reason for or goal of doing that? What is meant by "all generalized limits"? Is the reason for compactification to define a space so it is not infinite? How to reconcile the seeming contradiction of "enlarge" space by means of "compactification"?

The first sentence of the second paragraph seems to say the "compact space" ("BX") contains X. But the text initially seemed to describe X as the original space that needed to be enlarged...so why is X now "contained" in something else if X was being enlarged?

What would be a simple non-mathematical way of saying "bounded continuous function"?

These are the kinds of questions a general reader might well ask. I believe a highly technical topic such as this one should be, and can be, explained in the Introduction with simple everyday language. A sentence like, "A key property of βX is that every bounded continuous function on X extends uniquely to a continuous function on βX, and this universal extension property characterizes the Stone–Čech compactification" should not be present in the Introduction. An explanation of what that sentence means could certainly be present, but the language must be crafted so as to be understandable by anyone. I believe that can be done.

I encourage technical expert-editors not to worry that Introductory text will seem too simple or lack precise technical terminology. The goal of introductory text is to...wait for it...introduce the topic in wording understandable to lay people. That means avoidance of unfamiliar technical terms and phrases, linked or not. The articles linked from words in the existing Intro contain equally abstruse terminology in their introductions, so linking, as technical editors seem to assume, does not offer a quick answer to a general reader's question: what does that word mean? I believe the introduction to every article on every topic should stand completely on its own, without dependence on links. Links can be included, but only for supplemental information, not for basic understanding of what the introduction is talking about.

Technical editors can be reassured that the remainder of the article, after the Introduction, affords the opportunity to describe the subject in precise highly technical language and formulas. Text in the body can certainly contain plenty of links to articles with further explanations and definitions. Text in the introduction should stand on its own and not require any kind of specialized knowledge or education. DonFB (talk) 00:17, 21 November 2025 (UTC)

So your response is basically why I think the goal of making the introductory section readable to a general audience is not achievable and therefore not the correct goal. You read even Tito's slightly gentler version and you feel like "I've wandered into the middle of a conversation and I have no idea what's going on". Which is accurate. However, the conversation is available for you to look up if you want to.

We can have content that describes the things you are talking about. We can't in any useful way have it at the start of every topology article. You would have to re-teach topology to a general audience every time, and the real article wouldn't start till that was done. That doesn't wind up being helpful for anyone. --Trovatore (talk) 00:43, 21 November 2025 (UTC)

This seems natural under the current guidance. "One level down" from SCC is, maybe, fourth-year undergraduate math major. I think we can go a little further than this in terms of "academic level", but this honestly seems like the wrong sort of metric. Someone interested in math, but not necessarily educated to some particular level, should be able to say "wow, man", and situate the article in their own hierarchy of interest, without some rigid expectation of academic achievement. To be sure, most topics require a lot of background to convey. (As a number theorist who frequently has to talk to other mathematicians, I'm the first to admit it, lol.) But many things can be introduced on a first impression so that they convey meaning to someone who isn't deeply schooled in the relevant area. Then again, there is a point at which we do demand from even modestly sophisticated readers that "wow, man" is not enough ;-) PS: FWIW, I think Borel hierarchy would have been more intractable than SCC for a basic reader, and within your legerdemain. Tito Omburo (talk) 01:09, 21 November 2025 (UTC)

My view is that Borel hierarchy should be merged into Borel set, which would mean we wouldn't have to worry about its lead section per se. I could do that. There are differing views on which aspects of the subject are most important and it would involve re-opening arguments that I'm not thrilled about revisiting. --Trovatore (talk) 01:32, 21 November 2025 (UTC)

Vaguely feel that Borel hierarchy is more important than the basic Borel set article, owing to its fundamental importance in descriptive set theory, e.g., Kechris, Glimm-Effros. Not really my area though. More pragmatically, perhaps, this bullshit (written by one of two openly-declared Fields medalists on this site) is currently transcluded in the Borel set article: {{pointclasses}}. Tito Omburo (talk) 01:46, 21 November 2025 (UTC)

Re to Trovatore: I'm not challenging anything you said; not sure why you think so. You wrote: "So your response is basically why I think the goal of making the introductory section readable to a general audience is not achievable and therefore not the correct goal." My whole point is that the introductory section (of any article) can and should be made, in your words, "readable to a general audience". In reading Tito's revisions, I feel that too much of the text remains overly difficult for a general reader. My view is that broad concepts about any technical subject can be introduced and explained in an Introduction section without using multiple unexplained unfamiliar terms. In a great many cases that I've seen, supposedly explanatory links from tech words and phrases in an introduction show the reader additional article introductions filled with their own tech terms and jargon, taking the reader farther afield from his original desire to simply learn a few basic facts about a subject. I think writing one level down should be applied, where helpful, in the body of the article. I think the Introduction should be written for a general audience without regard for any "level". DonFB (talk) 05:07, 21 November 2025 (UTC)

So I think I've made my position pretty clear. I don't think what you want is possible. There is too much stuff to explain; it can't be done in a four-paragraph lead section. If you think it can be done, why don't you prove me wrong and do it? If you need help understanding it first, hit me up; I'm retired and it could be an interesting project. (Note that I'm not promising to spend unlimited effort on it and it could take quite some time.) But just insisting that it is possible, without saying how, just sounds like a fixed belief rather than a position informed by evidence. --Trovatore (talk) 05:19, 21 November 2025 (UTC)

Trovatore: Quite correct: I don't understand it; that's why I haven't tried to revise it. But I've seen plenty of articles in the popular press (Scientific American, Discover, Quanta) that do a consistently better job than Wikipedia in explaining technical topics without resorting to loading their opening paragraphs with jargon the way Wikipedia articles so often do. That's why I think it's possible for this encyclopedia to communicate with equivalent clarity.

Regarding your offer to help me understand it: we could start with the question I asked above:

"What would be a simple non-mathematical way of saying 'bounded continuous function'"? DonFB (talk) 06:39, 21 November 2025 (UTC)

We should take that off-line. There's a lot more to unpack in even that short phrase than you might guess, and I'm not sure it's on-topic for this page. --Trovatore (talk) 07:12, 21 November 2025 (UTC)

Agree, we should not load this page with granular discussion of a particular article. The article Talk page would seem to be the proper place. As Tito said, it's not a high priority article, but maybe the exercise, if successful, might serve as a kind of procedural template for improving other articles. DonFB (talk) 09:06, 21 November 2025 (UTC)

Well, no, we're not discussing how to improve the article; we're helping you personally understand the content so you will be able to advise how to improve the article. E-mail, or a subpage in one of our user spaces. Or could maybe even be a subpage of the article talk page. --Trovatore (talk) 19:31, 21 November 2025 (UTC)

A subpage of the article talk page works for me. DonFB (talk) 21:11, 21 November 2025 (UTC)

OK, started at talk:Stone–Čech compactification/Help for editors. --Trovatore (talk) 22:13, 22 November 2025 (UTC)

Thanks for follow-up. I'll reply in full presently. DonFB (talk) 05:08, 23 November 2025 (UTC)

[after e/c] I don’t think that’s quite right. As I suspect Trovatore will articulate more precisely, “one level down” is usually practical, and “two levels down” is plausible in many cases. What becomes unreasonable is expecting an article on a technical topic to descend ten levels and still remain about the topic at all. The guideline echoes Einstein’s point: simplify as far as possible, but not beyond the point where accuracy or verifiability breaks. Tito Omburo (talk) 05:19, 21 November 2025 (UTC)

We're talking about "one or more levels down", not "someone who never got past high school algebra class".

@Tito Omburo it might be helpful to give even slightly more context. For example, it might be useful to give a quick gloss to "compact space", and maybe even a sentence about why we would want a space to be compact. –jacobolus (t) 00:09, 21 November 2025 (UTC)

It might be helpful to work on adding more introductory context to Compactification (mathematics), and then wikilink to that more prominently. –jacobolus (t) 00:14, 21 November 2025 (UTC)

Excellent points, from DonFB and jacobolus, but I will accept this modest improvement as a "win" for the guideline. This is not exactly a high-priority article. Tito Omburo (talk) 00:24, 21 November 2025 (UTC)

Footnotes to explain terms?

Can explanatory footnotes be an additional strategy for cases where we have to use and explain a term but the explanation is too wordy to place them within the text? This current FAC makes use of that option quite a bit, for example. If not discouraged, should this strategy be included in the guideline? Jens Lallensack (talk) 21:07, 19 November 2025 (UTC)

I think that's an excellent idea. Probably a single well-crafted sentence should suffice. --Trovatore (talk) 22:33, 19 November 2025 (UTC)

Sometimes it can be helpful, but authors should be careful because most readers skip the footnotes, so the content of the footnote should generally be more detailed information for the curious expert rather than basic context for an unprepared reader. I don't personally think the use of footnotes to gloss technical terms in Misti seems very effective, and I wouldn't recommend copying this approach. –jacobolus (t) 22:55, 19 November 2025 (UTC)

I find that they're especially helpful when the basic explanation isn't quite right, but where the bit that would make it right would be treated as a quibble by many or most readers. We can't have outright lies-to-children; that's just a betrayal of the reader's trust. But if there's an immediate correction in an efn, it doesn't seem so bad and may be the least problematic way of introducing some things. --Trovatore (talk) 23:13, 19 November 2025 (UTC)

I really don't think it's that helpful to have:

[...] The inner crater contains a lava structure (either a volcanic plug or a lava dome) with active vents that emit volcanic gases [wikilink to 'fumarole']. [...]

[...] since then, phases of increased fumarolic activity have sometimes been mistaken for eruptions.

[...]

Notes

References

Sources

• Chen, A.; Ng, Y.; Zhang, E.; Tian, M., eds. (2020). Dictionary of Geotourism. Singapore: Springer. ISBN 978-981-13-2538-0.

This is trying to be clever, but the result is overcomplicated and confusing for readers and editors alike. It would be better to use the word 'fumaroles' directly in the first paragraph, with a parenthetical gloss, and then leave readers to figure out that 'fumarolic' refers to the previously defined 'fumaroles', skipping the second wikilink, textual footnote, and reference footnote. A brief gloss on 'fumarole' in this context doesn't need to be sourced, and if there is a need for sources about fumaroles, they should be linked from the appropriate place(s) in the article body.

The article does the same kind of thing several times, but readers would be better off with inline glosses instead of explanatory footnotes in basically every such case. It would be helpful to additionally gloss several other unexplained jargon terms used, and it might also be helpful to e.g. mention that "the smell of hydrogen sulfide" is usually described as a "rotten egg" smell. Overall this article is not particularly accessible to someone who doesn't already know a lot about volcanos; a copyedit/screen for accessibility to non-technical readers would help quite a lot, in my opinion, if anyone feels motivated to take that on. –jacobolus (t) 23:24, 19 November 2025 (UTC)

Oh, I agree about the fumarole thing. That's super-awkward. For an example of what I was talking about, look at the discussion in The Pirates of Penzance about the fact that 1900 was not a leap year. --Trovatore (talk) 23:50, 19 November 2025 (UTC)

Sure, pedantic trivia irrelevant to the main point of the narrative are worth moving into footnotes. I don't think that's what Jens Lallensack was asking about though. –jacobolus (t) 23:59, 19 November 2025 (UTC)

• Thanks, makes sense. Pinging @Jo-Jo Eumerus: as they are the author of the article discussed above. --Jens Lallensack (talk) 07:29, 20 November 2025 (UTC)