Wikipedia talk:Make technical articles understandable/Workshop
Latest comment: 32 minutes ago by Jens Lallensack in topic Thoughts from Jens
Thoughts from Jens
edit@Femke: As requested, here my thoughts, I hope they help:
- That the lead should be more accessible than the body makes sense. But in practice, I have my problems with this recommendation. In an article I reviewed today, both lead and body used the term endemic, even though "native" would be totally sufficient in the lead (the technical term is important for the body though). But if we use "native" in the lead and "endemic" in the body, we use two different terms for the same thing, and I would argue that this makes it even worse (the reader assumes that we mean to different things when we use different terms).
- Per your suggestion below, I've now included the guidance to avoid using different terms. My preferred way to do this is probably to use native in the lead, and reverse gloss 'native (endemic)' in the body. But normal glossing might also make sense to ensure readers we're talking about the same thing. —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- I wonder what precisely a "technical article" is. Some otherwise excellent history articles introduce a ton of names of involved people, making it very difficult to keep track of them all, especially when they change their titles during the story. That can make the article hard to understand. I am not sure if that falls within the scope of WP:MTAU?
- A while ago, I suggested we change the title of the guideline to 'Make articles understandable', which did not gain traction. In terms of FAC, I think the guideline is cited across all topics with jargon (from law, philosophy to the natural sciences and maths). I plan to ask a few folks in the social sciences to comment, so that we can have more examples from these subjects and it's more obvious that it's not only natural science. I imagine the 'technical' aspects of history, such as relevant concepts and terms, fall within scope, whereas the introduction of new names and the expectations people remember them might not? Again, in FAC words, that would fall short of writing 'engaging' prose instead. —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- Use wikilink only when you expect most of your readers to be familiar with the jargon – No, we always should wikilink in addition. The sentence should refer to the case where we only rely on the wikilink without additional in-text explanation.
- Done. —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- Use plain English and add jargon between brackets once – People told me not to do this (both in the German and English Wikipedias), and I tend to agree with them. The less correct term should always be the glossed one. Doing this consistently can also increase clarity (it is not always evident to a reader that some information provided in a gloss is supposed to be an explanation of a term, and being inconsistent here increases this confusion). An extreme example, just to make the point: In some articles, I explained the difficult-to-explain term basal like this: The species is basal ("primitive"). After this, readers will get the idea, and that's enough. But "primitive", when taken literally, is incorrect and highly problematic (I don't do it anymore for that reason). If we would instead write The species is "primitive" (basal), that would be plainly wrong.
- My preferred route to explaining jargon is where the reader is never left confused. When you gloss jargon, there's always a short period before you get to the gloss + the expectation that people memorize the jargon. This tip comes from the NHS, which has perfected the art of explaining difficult concepts. You're right that your example wouldn't work. Is there a way to rephrase to ensure people use this wisely? —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- But if we gloss the technical term, that basically means our common-language replacement term is that imprecise that an additional clarification is needed. When reusing the common-language replacement later, we would have this imprecision again but this time without the clarifying gloss. The other way around (reuse the technical term) ensures precision and clarity throughout. Or did you mean to propose that we only gloss the technical term when we do not re-use the common-language term later? If so, that not clear. --Jens Lallensack (talk) 10:59, 31 August 2025 (UTC)
- My preferred route to explaining jargon is where the reader is never left confused. When you gloss jargon, there's always a short period before you get to the gloss + the expectation that people memorize the jargon. This tip comes from the NHS, which has perfected the art of explaining difficult concepts. You're right that your example wouldn't work. Is there a way to rephrase to ensure people use this wisely? —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- Not sure, but maybe we need some brief discussion about the factors that make an article of interest for a broader audience. What about highly specialised topics that, for some reason, get a certain amount of public exposure (e.g., dinosaur species, pottery displayed in a museum, or something of regional interest, recent media coverage – should those be more comprehensible than similar topics with less exposure?).
- They should be, yes, but to what extend can we expect editors to find this information out? Recent media coverage might be relatively simple, but whether pottery is displayed is for instance quite tough. Do you have any suggested wording?
- I don't, it was just a thought --Jens Lallensack (talk) 10:59, 31 August 2025 (UTC)
- They should be, yes, but to what extend can we expect editors to find this information out? Recent media coverage might be relatively simple, but whether pottery is displayed is for instance quite tough. Do you have any suggested wording?
- Many Wikipedia readers speak English as a second language and may be unfamiliar with more flowery or otherwise difficult words. – I argue that this point, in many cases, argues in favor of the technical term, as the technical term is often easier to understand for non-native speakers. For example, when I started in the English Wikipedia more than a decade ago, I got confused about the word "rearwards" (in an anatomical context) and had to look that up. The more technical "posterior" would have been much easier for me.
- You're absolutely right, and the aim of this section was to talk about the non-jargon parts of the sentence. I've clarified by talking about idiomatic English, which is probably native speakers are most surprised that ESL speakers do not understand their writing. Many of my friends were surprised I was able to follow lectures about biology in Spanish, but really struggled with day-to-day conversations. —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- replace facilitate with help – I think this is one is problematic, as the meaning is slightly different. See how the word is actually used in Wikipedia articles [1]; I would argue that only in a minority "facilitate" could be replaced with "help".
- Done, replaced with terminate --> end. —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- Use bullet points where appropriate. – I would way better remove this one. Bullet points are of limited use in Wikipedia (and are only sparingly used). They can be misused to put undue weight, and are chat-gpt style that I personally do not want to see more of.
- I think bullet points can be extremely useful, for instance in a list of less common symptoms for a disease. The alternative is a long sentence, with elements that are easy to miss. It's a shame chatGPT is ruining bullet points and m-dashes, but I'd rather not kneejerk away from it. —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- MOS:EMBED says we should use lists only when appropriate, and there are many ways to misuse such lists (they give undue weight to the listed points; they serve as dumping ground for excessive detail, etc.). Two articles we both got involved with recently Air pollution and Flower) do not use any such lists, and they are rarely used. The wording in the guideline would suggest to make broader use of them, but I think that this goes against other policies, which seem to want to limit their use (e.g., WP:STAND says "Do not use lists if a passage is read easily as plain paragraphs", and even though this refers to stand-alone lists, it is my impression that the same is generally expected for articles, too). --Jens Lallensack (talk) 10:59, 31 August 2025 (UTC)
- I think bullet points can be extremely useful, for instance in a list of less common symptoms for a disease. The alternative is a long sentence, with elements that are easy to miss. It's a shame chatGPT is ruining bullet points and m-dashes, but I'd rather not kneejerk away from it. —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- Instead, I would suggest to add "Use the same word for the same thing", and a point on ambiguity, which is critical as well. See here for examples and links to more examples.
- Added a sentence that 'elegant variation' can be confusing..
- Is there a good example for the first paragraph of "Explain new concepts"?
- The closest example I was able to find was from heat pump: A heat pump is a device that uses electric power to transfer heat from a colder place to a warmer place. Specifically, the heat pump transfers thermal energy using a heat pump and refrigeration cycle, cooling the cool space and warming the warm space, but not quite what I'm after. I'll continue looking. —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- analogies need to be written in an encyclopedic way and be attributable to reliable sources. Extensive explanations without a specific source may constitute original research, or original research by synthesis. – sometimes these need sources, but I would say generally these should not have sources, and that we should make that clear (also per WP:CITEKILL). We always need some degree of synth in order to understand a source and summarise it in a Wikipedia article. Explaining a term how we understand it does not really make it more synthy. At WP:SPOTCHECK, we have "In-text explanations of terms and concepts merely aimed at making technical article understandable do not usually require a source" (Disclaimer: I wrote that myself, but so far nobody contested it). Incidentally, the example analogy with the DNA and the zipper is not given in the source cited in the DNA article (although "unzipping" seems to be a jargon term for pulling apart DNA). So I think that we should either look for a different example that is properly cited, or we just abandon that requirement. Finding creative ways to explain things should be allowed.
- I agree that explaining things generally falls under paraphrasing, as should not require sourcing. With analogies I'm less certain: there are analogies that might feel right, but might reduce understanding of the topic at hand. For instance, the greenhouse as an analogy for the greenhouse effect only works at a surface level, and sources that employ the analogy always detail how a greenhouse traps heat differently from greenhouse gases. I've removed the sentence that extensive explanations in general require a separate source, as it didn't fit in that section, but left the comment about sourcing for analogies. —Femke 🐦 (talk) 09:31, 29 August 2025 (UTC)
- Ok, agreed. --Jens Lallensack (talk) 10:59, 31 August 2025 (UTC)
- I agree that explaining things generally falls under paraphrasing, as should not require sourcing. With analogies I'm less certain: there are analogies that might feel right, but might reduce understanding of the topic at hand. For instance, the greenhouse as an analogy for the greenhouse effect only works at a surface level, and sources that employ the analogy always detail how a greenhouse traps heat differently from greenhouse gases. I've removed the sentence that extensive explanations in general require a separate source, as it didn't fit in that section, but left the comment about sourcing for analogies. —Femke 🐦 (talk) 09:31, 29 August 2025 (UTC)
- I think that the key take-away of WP:MTAU is that we should provide in-text explanations (e.g., glosses) of terms and concepts. But in the draft, that comes a bit short, and glosses are proposed for jargon terms, not for concepts. A frequent point of discussion is also the density of such glosses: At what point do we compromise reading flow? I think that more examples would help.
- My thinking goes in the other direction. In general, I find articles that rely on frequent glossing really tough to read. It makes Wikipedia a memory game, where the readers has to memorise all the new terms that are introduced. One of the goals in the rewrite is to show alternatives to glossing (e.g. reverse glossing, wikilinking explanations), or making glossing less painful (giving 'hints' upon reuse of jargon). Question: What do you mean by glossing concepts? —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- Ok. I agree that we should avoid excessive use of glosses, and be more creative with improving comprehensibility. --Jens Lallensack (talk) 10:59, 31 August 2025 (UTC)
- My thinking goes in the other direction. In general, I find articles that rely on frequent glossing really tough to read. It makes Wikipedia a memory game, where the readers has to memorise all the new terms that are introduced. One of the goals in the rewrite is to show alternatives to glossing (e.g. reverse glossing, wikilinking explanations), or making glossing less painful (giving 'hints' upon reuse of jargon). Question: What do you mean by glossing concepts? —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
- I pointed some things out on that Writing tips page that seem to be missing here. I will just copy/paste the examples:
- avoid scientific notation that is unfamiliar to many readers: (Dodson (1998) argued that ⇒ In 1998, Dodson argued that
- context matters. Explain why the information is significant. E.g., the femur has a prominent ridge ⇒ the fourth trochanter, a ridge on the femur where leg muscles attach, is unusually prominent in this species
- Often, we can replace a jargon term directly with the explanation, and link the entire explanation to the respective article. E.g., it grows in direct proportion to carapace width …
- I've added the first and last example to the workshop text. I agree that context matter and happy to put this in the text, but the example is still too technical for a general guideline. I'll try to think of another one. —Femke 🐦 (talk) 07:18, 28 August 2025 (UTC)
Jens Lallensack (talk) 21:30, 24 August 2025 (UTC)
- Thanks Jens Lallensack! Incredibly useful feedback. I've incorporated most of it, except for the few I didn't quite understand (see questions). Let me know if you know others that might be interested in providing feedback. —Femke 🐦 (talk) 09:31, 29 August 2025 (UTC)
- Thanks, just few replies above. --Jens Lallensack (talk) 10:59, 31 August 2025 (UTC)
- Thanks Jens Lallensack! Incredibly useful feedback. I've incorporated most of it, except for the few I didn't quite understand (see questions). Let me know if you know others that might be interested in providing feedback. —Femke 🐦 (talk) 09:31, 29 August 2025 (UTC)
What is the objective?
editI have asked to comment on this. Which I nay or may not do. But before deciding, what is the objective? To give a concrete example, if we are trying to improve the usability of the guideline then it is arguably worth working on the one level down section: I can just about see how, heavily caveated, it may help nudge some editors in some circumstances in a helpful direction. If we are attempting to come up with a policy how understandable technical articles need to be then it needs to go, root and branch. Ie are we aiming to generate a standard, or a "how to"? And if the answer is "both" then good luck to you and I am out of here. Gog the Mild (talk) 20:29, 28 August 2025 (UTC)
- My goal is to make the guideline more useable, taking inspiration from how the Manual of Style is written. Coming up with an entirely new standard for how understandable articles should be would be tough, given the opinions diverge so much on this. That standard is mostly detailed in the audience section, and so far, I've not changed the spirit of the section much. When you say, 'it needs to go', are you referring to the old text or the workshop? Keen to hear your thoughts on ONEDOWN. —Femke 🐦 (talk) 07:00, 29 August 2025 (UTC)
Feedback from Phlsph7
editMoved from User talk:Phlsph7
Hi Phlsph7! I was wondering if you had time to give feedback on the workshop text for the understandability guideline (comparison with the existing text). One goal of the rewrite is to talk more about how you use plain English to make articles understandable, which you always do well in your articles. Would you be able to have a look and give feedback? I'm also keen to get an example in from philosophy, as the examples now draw too heavily from biology. Would you be able to provide one?
Thanks in advance! Also happy to trade feedback here for a full review at FAC. —Femke 🐦 (talk) 07:23, 28 August 2025 (UTC)
- Hi Femke, that sounds like an interesting project! Some comments:
- I'm not sure about the sentence "Wikipedia's style is encyclopaedic, not academic" since the two need not conflict.
- They usually do conflict. You do have occasional academic texts that excel in writing ONEDOWN, but typically the expectation is that these sources are read by people with high reading skills and at least some topic expertise. Of course, in our top articles, the sourcing is as strong as you'd expect from academic reviews, but the style is distinctive, I'd say. —Femke 🐦 (talk) 08:53, 30 August 2025 (UTC)
- The mention of 8–15 words seems to implicitly suggest a goal of staying below 8 words per sentence, which is not very realistic. I assume that understandability decreases continually as sentence length goes up, so it's difficult to point to a specific length.
- I've reworded to omit the 8 words. At 8 words, the cited study found 100% understandability, which dropped to 90% at 15 words, and 50% at 28 words. Reducing the number of sentences above 15 words is a more realistic proposal. Also added a note on the study itself. —Femke 🐦 (talk) 10:35, 29 August 2025 (UTC)
- A short mention of preferring active over passive voice could be added. This is discussed, for example, in Dennis 2021 pp. 86–87
- Added that back, but with a bit of a caveat to respond to previous objections that passive voice can sometimes make sentences more concise, allowing the writer to omit unnecessary details.
- I guess many of the suggestions are rules of thumb: they work often but not always so one shouldn't trust them blindly. Phlsph7 (talk) 09:28, 31 August 2025 (UTC)
- Added that back, but with a bit of a caveat to respond to previous objections that passive voice can sometimes make sentences more concise, allowing the writer to omit unnecessary details.
- In the section "Structure articles well", you could mention WP:SUMMARY somewhere, since getting the right level of detail is also relevant to accessibility
- I feel that works better in 'technical content' where it's now.
- Some philosophy examples for avoiding jargon could be:
- a posteriori: known from experience
- a priori: known without experience
- deontological: based on duty
- abduction: inference to the best explanation
- sound argument: valid argument with true premises
- have replaced one of the biology examples with 'a posteriori', saying that you can replace a posteriori with It is known from experience that … —Femke 🐦 (talk) 08:53, 30 August 2025 (UTC)
- Since we are talking about simplification: replace "formulae" with "formulas"
- Done. —Femke 🐦 (talk) 08:46, 29 August 2025 (UTC)
- I would make the first paragraph of the section "Review" less about an explanation of psychological effects and more about the practical consequences. You could start with something along the lines "Editors with significant background knowledge may overestimate how much the average reader knows about the topic. This effect, known as the curse of knowledge, may lead them to...". You could then go on to describe things like assuming that readers know what technical terms mean or trying to pack too much information in a short passage. One solution is already given in the next paragraph: ask for feedback from others. Another solution could be to imagine an audience (e.g. a specific student one knows) and assess whether they would understand the current explanation. More details on psychology could be added in a footnote after "curse of knowledge".
- I've rewritten the section, but only partially in that direction. I had initially intended to give the advice that editors should imagine a certain audience. However, when I started editing the curse of knowledge article to make sure I fully understood, I discovered that this advice has been tested, and proven ineffective to cancel the cognitive bias. Seeking feedback is the only thing that body of literature recommenends so far. I've now made the link between the effect, our writing, and how to combat it more explicit. —Femke 🐦 (talk) 08:46, 29 August 2025 (UTC)
- Ah, I was not aware of that. The new version works fine. Phlsph7 (talk) 09:25, 31 August 2025 (UTC)
- I'm not sure about the sentence "Wikipedia's style is encyclopaedic, not academic" since the two need not conflict.
- Thanks Phlsph7. Really useful feedback :). —Femke 🐦 (talk) 08:53, 30 August 2025 (UTC)
Thoughts from RoySmith
editI mentioned this on my talk page, but I'll repeat it here. Encyclopedia articles and journal articles have different goals. The goal of an encyclopedia article is to educate somebody who knows less than the author. In that way, it is similar to a textbook. The goal of a journal article is (at least in part) exactly the opposite: it is to impress people with how much you know or how good your work is so they will approve your thesis, fund your grant application, give you a job, grant you tenure, etc. See, for example, Least publishable unit. For people who are used to that sort of writing, it may be difficult to switch gears, or even imagine that an alternative exists.
This distinction is implicit in how the two give credit to their authors. In a journal article, the author's name is typically the very first thing after the title. Before the reader even finds out what was done, they find out who did it. In a wikipedia article, you have to go digging into the edit history. Many of our casual readers may not even realize this history exists, and if they do find it, they'll often only discover fanciful author names like DinosaurGuy47. RoySmith (talk) 10:49, 31 August 2025 (UTC)