Wikipedia talk:Make technical articles understandable/Archive 3

This is an archive of past discussions. Do not edit the contents of this page. If you wish to start a new discussion or revive an old one, please do so on the current talk page.

Archive 1

Archive 2

Archive 3

I think this section needs a bit of reorganisation and a little trimming of some dubious suggestions (per Tony's comments). Some of the "rules" are so brief that it seems odd to use sub-sections for each one. I think there should be a section or sub section specifically dealing with jargon and technical terms and the various techniques to deal with them. We probably also could do with a short sub section on general advice for reducing the reading level of prose.

More suggestions like the "Write one level down" one would be good. Offer them here if you don't feel brave enough to add them directly. Colin°^Talk 22:44, 16 February 2011 (UTC)

• There is some pretty good and frequent commentary on all kinds of writing sites that say to shorten the sentences if the material is technical. The flowing, multiclause approach that one would use in a history narrative is just too hard when the words themselves are tricky. 12 words is an exaggeration, but certainly more direct prose (because of the inherent difficulty of the words) is a VERY frequent recommendation. Averaging (i.e some may be longer) no more than 20 words is a good rule of thumb. And NEVER over 35 words, in technical text.
• Many sites also recommend shorter paragraphs when the mateiral is technical (and I agree). Not saying that we should have abunch of one liners. But definitely a 10 sentence paragraph wall of text is too painful when the topic itself is abstract and fifficult. And if you have 10 sentences, you can easily chop it into 2 or 3 paras. Can organize into smaller topics.

TCO (talk) 01:03, 17 February 2011 (UTC)

Thinking about comments above, perhaps we should consider shorter paragraphs even when that means having five or six short paragraphs in the lead, rather than four long ones. WhatamIdoing (talk) 18:12, 18 February 2011 (UTC)

I think you can keep it at four, but STILL make them shorter. By cutting some detail, you will be reducing the technical complexity of the lead. The detailed content is in article anyhow. BTW, it's interesting to me that the same people who struggle (or think it unimportant) to write readable technical content, also tend to overlong leads. I see a correlation and suspect an independent variable producing both effects.  ;) TCO (talk) 19:36, 18 February 2011 (UTC)

Not always. There are "details" that could be cut from the lead of Exterior algebra that would have made it less comprehensible, not more. In fact, if you did a standard copyedit for concision, you'd lose some of the features that helped me get through it, like saying "which is called X" and the example of multiplying polynomials. "Shorter" is not automatically "more readable". Shorter can be less readable. WhatamIdoing (talk) 20:14, 18 February 2011 (UTC)

Maybe so for math, where the content is so abstract and builds on so much previous. I think for chemistry, forced nutshllization will often make the lead more readable (and the details of synthesis and the like are in body text.)TCO (talk) 20:21, 18 February 2011 (UTC)

I think we have to consider the difference between tangible topics and intangible ones. Tangible ones are nearly always possible to rephrase into a meaning that can be understood easily, eg enzyme inhibitor explains how these affect the average person's life. Intangible topics like advanced math, quantum theory, astrophysics, etc., are much more difficult to put into terms that the average person will understand, without treating the topic to a trivial point that may be insulting. The approach being done in the exterior algebra seems to be trying to do this right, but I can tell it is not easy. But I think if we can focus on not so much what the topic is but what the topic can do for us, as early as possible in the lead, helps to ground the topic enough. --MASEM (t) 22:05, 18 February 2011 (UTC)

I've just had a bit of inspiration about how to structure the guidance. I hope you are as keen on it as me. The idea I have is that we take the three issues from the new Audience section (familiarity, readability, motivation) and use them as the top level sections. Perhaps not those words; maybe a phrase for the section heading works better. But regardless, those three issues can be used to group the guidance we already have and any more we add. Obviously some of these issues are not unique to technical articles, but they can be worse for technical articles and if one of them is unavoidably difficult to reduce (such as familiarity with the subject) then reducing the other issues can go a long way to help.

Motivation

The "Put the most understandable parts of the article up front" advice fits in here as does the related issue of the lead (see my comments about about combining these issues). We need to grab the reader's attention up front. We need to avoid puting them off as soon as they start reading the body. We need to find a way to get them to read through to the end (even if they skip bits). The prose needs to be engaging. Pictures with captions can encourage readers to read the section they are in. The old chestnut about how equations lose readers.

Readability

We've got some good advice forming here, probably better than some of the existing advice, and in the linked web sites that we could use. I agree about the long sentences. I don't think the "conversational English" advice is wise: the prose is still formal. We can describe how to measure the reading level of an article (external websites?) and perhaps what reading level we should be aiming for.

Familiarity

The ideas about not assuming familiarity with the subject (works for most articles), about writing one level down (works for advanced academic articles), about avoiding or carefully handling jargon and technical words. About not using language that assumes the reader is one of the experts.

Thoughts? Colin°^Talk 08:44, 17 February 2011 (UTC)

You're doing good work, man. I'm too tired to engage myself. I do think this is very important and am glad you are wrestling with it.TCO (talk) 15:45, 17 February 2011 (UTC)

I think this is a good way to split up the advice. The one thing I would add in Motivation is also not to tick off the expect - ok, we made lead off with "simple" language that they don't need, but as long as the lead is summarizing the article correctly, the expert will understand "Ah, this article will cover subjects X and Y of this topic in this relative order, I can go jump to those". --MASEM (t) 17:05, 17 February 2011 (UTC)

I'm not totally following you. And I think someone further up suggested that the lead summary of the body doesn't necessarily take the same order as the body does. We've got a contents listing if folk want to jump to a section. Colin°^Talk 18:29, 17 February 2011 (UTC)

I think an essential part of this guideline is that we should not sacrifice accuracy or technical usefulness in the name of making the article more accessible. This is currently buried in the "Rules of thumb" section, with some discussion towards the end of the new "Audience" section. I think it should be given greater prominence, perhaps by mentioning it in the lead or the nutshell description. The nutshell description, I should add, now reads:

This page in a nutshell: Strive to make each part of every article as accessible as possible to the widest audience of readers.

However, this is at odds with some of the recommendations of the guideline. Perhaps something like the following would be a more balanced way to summarize the guideline:

This page in a nutshell: Strive to make each part of every article as accessible as possible to the widest audience of readers without sacrificing the accuracy or technical usefulness of the content.

Another option is:

This page in a nutshell: Strive to make each part of every article as accessible as possible to the widest audience of readers, with special attention to the earlier sections, without sacrificing the accuracy or technical usefulness of the later sections of the article.

Any thoughts? Sławomir Biały (talk) 15:19, 28 February 2011 (UTC)

I disagree quite strongly. I think you are coming at it from the wrong direction. Our writers on technical articles generally need guidance to help them make them accessible. They don't need guidance to make them accurate or useful for professionals.

• Accuracy is not a requirement. Being correct is fine. For example, if I say "viruses are smaller than bacteria" then that's correct but not accurate. I'd need to given ranges in microns for it to be accurate. The degree of accuracy is an editorial judgement and in many places being inaccurate is good.
• The "technical usefulness" is a vague phrase. I'm not totally sure what you mean by it and I'd like to see an example where someone making something accessible to a wide audience made the text less "technically useful". There is lots of information that one could argue is "useful" (to someone) and "technical" but probably not appropriate. We are writing encyclopaedia articles here, not textbooks. One example,
  WP:MEDMOS
  discourages listing recommended dosages for drugs. This is "technically useful" stuff, but the recommendations vary from country to country, require a lot more knowledge about the patient to get right, are highly subject to vandalism and hence really dangerous when wrong. Since we're not a drug formularly, this isn't the sort of information we need to present to a reader just learing about some drug. (Yet another example of why "the sum of all human knowledge" is a lie).
• Let's not add the easy-earlier-harder-later stuff to the nutshell. It isn't always applicable (other than the lead/body split) and a nutshell is a nutshell, not a lead.
• It isn't possible to make a set of rules/guidelines such that they don't conflict at all. Judgement is always required.

Colin°^Talk 17:00, 28 February 2011 (UTC)

Colin, I think you have accuracy and precision backwards in this comment. "Viruses are (usually) smaller than bacteria" is reasonably accurate. (The largest viral particles are about the same size as the smallest bacteria.) It's just not precise: it doesn't tell you the size of a typical virus or bacteria, or whether you're measuring size based on genome or capsid size, or how much bigger the bacteria are.

As an example, it is accurate to say that breastfeeding reduces the risk of childhood leukemia. It is precise to say that exclusively breastfeeding four million babies for six months has a 95% chance of preventing a single case of childhood leukemia.

I think that we do need to sacrifice "technical usefulness". Wikipedia is not a textbook or a cookbook. "Type this code to make your computer start working" is certainly 'technically useful'. What's "technically useful" in an article is frequently not encyclopedic.

Additionally, for some topics, we occasionally even need to sacrifice strict accuracy (especially in the introduction). For example, I would have no objection to the article Atom treating electrons as though they are always physical objects, even though this isn't accurate, because it's close enough to accurate for the needs of this article. WhatamIdoing (talk) 17:26, 28 February 2011 (UTC)

You are right the example I gave was more about precision that accuracy. They are largely synonymous in everyday speech. But even your "accurate" breastfeeding example, isn't as accurate as some might like. Reduces the risk compared to what? Is this a study of white middle-class Americans, or Chinese rural farmers? Does it reduce all childhood leukaemias or just some types? These may or may not be important depending on the subject. Colin°^Talk 19:53, 28 February 2011 (UTC)

The nutshell description could be seen ad giving a license to remove or "dumb down" all of the technical content of an article, which this guideline is emphatically not recommending. I'm not worried about editors with experience in writing technical articles, but the less experienced or nontechnical editors. (For instance, removing all the content below "Motivation" in the exterior algebra article.) The current wording of the nutshell seems like a recipe for conflict. The guideline needs to accommodate both general readers and readers who already have some background in a subject. How about:

This page in a nutshell: Strive to make articles as accessible as possible to the widest audience of readers, with special attention to the earlier sections, without sacrificing accuracy by dumbing down the content.

Or something like this. Suggestions welcome. Sławomir Biały (talk) 17:37, 28 February 2011 (UTC)

We don't have a consensus that making earlier sections easier works for all articles. The current nutshell doesn't talk about whole articles, but about "each part of every article". It doesn't talk about general readers, but about "widest audience of readers [as possible]". So for a given section on a given aspect of your topic, make it as accessible as possible to the audience of readers of that section. I think you are seeing a "recipe for conflict" where there isn't one. And anyone who deletes huge chunks of text or edit wars, based on reading a guideline or policy nutshell but not the whole thing, is just trouble. I'm really opposed to the nutshell having opt outs on the accessibility aspect as they'll just get abused. This is a guideline on making technical articles understandable. It is not a guideline on making technical articles more accurate, more technically useful or whatever. The guideline does not request text is "dumbed down" and that's a pejorative term that we shouldn't be using. Colin°^Talk 19:53, 28 February 2011 (UTC)

Would the following be acceptable to you, then?

This page in a nutshell: Strive to make each part of an article as accessible as possible to its widest likely audience.

The current text of the nutshell makes it seem like every part of the article should be pitched at the same level, but from your post it seems that this isn't the intention. Sławomir Biały (talk) 20:26, 28 February 2011 (UTC)

Sławomir Biały, have you run into any actual problems with this, or is this (currently) a hypothetical concern? WhatamIdoing (talk) 20:19, 28 February 2011 (UTC)

Yes. I am constantly seeing this guideline used and abused, mostly by non-technical editors to plaster unsightly templates on things (often via "drive-by"). I agree with the need for our technical editors to have a guideline on making articles understandable. However, my concern is mostly with how this guideline will be received by non-technical editors who still need to understand that we strive to be a serious reference work on all kinds of technical topics. This goal isn't necessarily incompatible with accessibility, but there needs to be some understanding that highly technical information does have a place in the encyclopedia. Sławomir Biały (talk) 20:35, 28 February 2011 (UTC)

Drive-by tagging is a problem generally and we don't re-write or soften guidelines because some people get carried away. But really, arguing over the nutshell before the body of the guideline is improved is a bit like the lame newbie edits we all see to articles, where an anon adds something to the lead but not the body. Let's get the body right, were rather than second-guess what a sentence means, we can just spell it out in full.

Perhaps, just perhaps, some of those editors are telling you something. Colin°^Talk 21:59, 28 February 2011 (UTC)

Drive-by tagging can be irritating, but I'm not sure that spamming a tag onto an article is the same thing as demanding that advanced material be omitted or simplified into error. Have you encountered editors actually demanding that you provide less information, and claiming that this guideline prohibits the inclusion of advanced material, rather than asking for the advanced material to be made understandable? WhatamIdoing (talk) 22:52, 28 February 2011 (UTC)

I have encountered people on both extremes: those demanding abstract general definitions right away, and those insisting that there is no place for research-level topics in a general encyclopedia. This guideline needs to be able to explain, gently, to the first group of people why and how to make an article understandable to a wider audience. At the same time, it should make clear that technical content is appropriate subject matter for us. Sławomir Biały (talk) 00:54, 1 March 2011 (UTC)

Continuing discussion of nutshell

I recently removed the disputed nutshell:

This page in a nutshell: Strive to make each part of every article as accessible as possible to the widest audience of readers.

My earlier proposed compromise was this:

This page in a nutshell: Strive to make each part of an article as accessible as possible to its widest likely audience of readers.

As I see it, this makes somewhat clearer that the standard is different for different articles and even for different parts of the same article (without committing to whether the earlier parts of the article should be favored over the later). It also emphasizes something that the guideline itself now does, and that is that there is such a thing as a target audience, and this is not always going to be a "general audience", particularly for highly technical subjects. Perhaps someone else has a suggestion? Sławomir Biały (talk) 21:59, 28 February 2011 (UTC)

It is only disputed by you. The replacement text is self-defeating. It is sort of like saying "Strive to achieve what you think you'll probably achieve". I really think we should not be debating the nutshell at this stage. We have body text to sort out. This is a guideline on making technical articles understandable. Have I said that already? Perhaps the nutshell should say something about making articles accessible? Oh, it does. Good. Let's leave it for now. Colin°^Talk 22:04, 28 February 2011 (UTC)

Sławomir, would you stop edit warring over the nutshell. Put it back how it was. You haven't got consensus for change. Colin°^Talk 22:06, 28 February 2011 (UTC)

I don't understand. Surely this discussion shows that there isn't consensus for the new version of the nutshell. I'd be happy to see some constructive suggestions though. Sławomir Biały (talk) 22:15, 28 February 2011 (UTC)

Nobody, but you, is disputing this nutshell. Please put it back. The only constructive suggestion I have is that the nutshell contain the text it had earlier. Which was text used by Geometry Guy, if memory serves me. Colin°^Talk 22:31, 28 February 2011 (UTC)

As far as I can tell, there was never a nutshell until this edit. Sławomir Biały (talk) 23:21, 28 February 2011 (UTC)

How about this:

This page in a nutshell: This page provides guidelines on how to make technical articles accessible to a wider audience.

That seems like it would be difficult to object to. Sławomir Biały (talk) 01:07, 1 March 2011 (UTC)

That's not a nutshell. Have a look at all the other guideline/policy nutshells. You haven't actually come up with any concrete objections to the previous nutshell:

This page in a nutshell: Strive to make each part of every article as accessible as possible to the widest audience of readers.

There's absolutely nothing objectional about this. Are there any editors here who think we should deliberately make parts of an article less accessible than they are capable of being? Are there any editors here who think that it is good to deliberately narrow the audience for a topic/section that could have a larger audience?

It is not the purpose of a nutshell to list all the nuances and traps that good writers adopt and bad writers fall into. It isn't the purpose of the nutshell to settle disputes between editors who write something inaccessbile and readers who think it could be improved, even if those readers are wrong and the material is as accessible as it can be. Colin°^Talk 08:37, 1 March 2011 (UTC)

I object to the original version of "This page in a nutshell" on the basis that its wording (italicized) "Strive to make each [and every] part of every article as accessible as possible for the widest audience of readers." Its too absolute, it gives off fanatical vibes, and it discourages caveats that this discussion has touched upon. It is a complete oversimplification of what this guideline is and should be. Rilak (talk) 11:57, 1 March 2011 (UTC)

Here's what Geometry Guy originally wrote

What we do is strive to make each part of every article as accessible as possible to the widest possible audience of readers who might be interested in that material.

This is very close to Sławomir's suggestion 21:59, 28 February just above. Without the "What we do is" prefix, of course, it would be a suitable nutshell. I think Rilak is reading too much into and expecting too much of a nutshell. It is like a company mission statement. It doesn't say how we are going to do that (the nuances) and it doesn't mention the difficulties we face trying to do that (the caveats). Those are for the body. It says what we are trying to achieve through this guideline. It isn't the only guideline so we don't have to worry about thinking it is "absolute". Lots of guidelines have to be tempered by other guidelines. In fact most of our guidelines restrict our ability to build a better encyclopaedia in some way but in other ways they prevent it going badly wrong.

Let's look at the problematic words

• "Strive". Let's aim for something please. If folk really don't like that language then we could have "Ensure each and..." or simply "Make each and...". It does sadden me that aiming for excellence in something gets labelled "fanatical" or "zealous".
• "Each and every" part of "every" article. Are there some articles or some parts of articles where we want to make no or little attempt at making them accessible? If there are such articles or section, let's see some examples and identify why they should remain impenetrable.
• "accessible as possible". The "possible" qualifies this. If the text could be made more accessible and still achieve its aims, then why not?
• "widest audience" of readers. I hope the addition of "who might be interested in that material" helps here.

I hope this is sufficient that we can adopt this revised nutshell and focus on ways to make our technical articles understandable.

This page in a nutshell: Strive to make each part of every article as accessible as possible to the widest possible audience of readers who might be interested in that material.

Colin°^Talk 20:57, 2 March 2011 (UTC)

As noted above, the proposed nutshell is based on a comment of mine. My text can of course be used, but it should be used with care, as selective quotation may cause further problems. I have commented before that without the last clause ("who might be interested in that material"), I would disagree with this nutshell. With the last clause included (and carefully worded), I support it. Geometry guy 01:36, 3 March 2011 (UTC)

@ Colin: Colin, you said, "It does sadden me that aiming for excellence in something gets labelled [sic] "fanatical" or "zealous"." Do you think that excellence is one-dimensional? That is, if the article is deemed accessible, it is therefore of good quality, regardless of whether its accurate or not, and/or complete (and thus not misleading by omission)?

Regarding the nutshell. I propose something to the effect of: "When writing an article, accommodate audiences with different levels of technical background. Aim to make parts of the article that do not require extensive prerequisite knowledge accessible to a non-technical audience." Rilak (talk) 06:24, 3 March 2011 (UTC)

A good quality article is measured by several factors, including compliance with our different policies and guidelines. Each of WP's guidelines concentrates only on the bits that matter to that guideline. Here we are concentrating on what makes a technical article understandable. What makes an article great isn't an easy thing to put in a guideline because that requires some talent from the editors. If folk want to develop some guidelines on what makes a great Maths article, with guidance on dealing with conjectures, proofs, examples, formulae, etc, and guidance on making sure it is accurate and comprehensive then that would be great, but not what this guideline is about. Your proposed text is very weak guidance (it will have no effect IMO); its purpose seems to be to define the areas we aren't going to make accessible to any degree; and it assumes the audience is either techical with prerequesite knowledge or non-technical. But our audience may be very technical, though not in that particular subject. They may have a fair amount of prerequesite knowledge or almost none. This is why we've added good ideas like the "one level down" one, which can be applied to any section of any article. Colin°^Talk 08:57, 3 March 2011 (UTC)

Well at least we agree that quality depends on multiple factors. Regarding the audience: Being a mechanical engineer, for example, does not make one "an expert" on anything other than mechanical engineering. The same situation exists for every other topic combination. This is obvious. I have no prior knowledge of anyone considering a technical audience as being an audience with a PhD in anything other than what is being discussed. If the only arguments you have against the general sentiments of my proposed revision of the nutshell, are that you wish to define a technical audience as being one with qualifications in any topic but the topic of the article, then it is rather weak. Rilak (talk) 04:37, 4 March 2011 (UTC)

I don't follow what you are saying and it is clear you don't follow what I'm saying. Your proposal is flawed on many many levels. I'm not really intested in arguing with you over all the issues I have with it. If someone else thinks it has merit then perhaps it is worth debating. But it seems a non-starter to me. The proposal by Carl below seems much more attractive. It is positive and it is encouraging. It is only a nutshell after all, just something to say "Yes, I want to do that". The details of how to do that and how not to do it can be found in the body. Colin°^Talk 08:44, 4 March 2011 (UTC)

You said "...it assumes the audience is either techical with prerequesite knowledge or non-technical. But our audience may be very technical, though not in that particular subject." You are defining a reader as being technical when they have expertise in any topic except for whatever topic the article is about. What's wrong with this definition? It seems very likely that you are the only person who uses such a definition. Rilak (talk) 00:48, 5 March 2011 (UTC)

I agree that something about audience should be included. My worry about "who might be interested in the material" is that someone reading that without context might say, "well, anyone at all might be interested, so this is really no restriction". So I think that we should tighten up the "might" a little. For example,

Strive to make each part of every article as accessible as possible, keeping in mind the likely readership of the article.

or

Strive to make each part of every article as accessible as possible to the widest audience of readers who are likely to be interested in that material.

In the last part, I think "widest possible audience" isn't different than "widest audience". — Carl (

CBM · talk

) 01:58, 3 March 2011 (UTC)

I prefer the second one and support that. It expresses the nutshell in a positive way, whereas the first contains a negative and constraining clause. This is what I'm trying to get at with some of my imperfect arguments. We can think about this as a positive thing that will actually improve our articles and not take anything away from them, or we can view it is an annoyance where all we want to do is find exceptions. Of course we want to write accessible articles that are accurate and comprehensive. We need to develop and express ways of achieving that, and stick them in this guideline. Colin°^Talk 08:57, 3 March 2011 (UTC)

I've stuck your second proposal on the page. Let's move on now to improving the body of the guideline. Colin°^Talk 08:48, 4 March 2011 (UTC)

OK, great. Sorry I didn't respond yesterday. — Carl (

CBM · talk

) 11:42, 4 March 2011 (UTC)

"Dumbing down" and accuracy

In the previous thread, Colin suggested that the phrase "dumbing down" shouldn't be used because it is pejorative. Likewise, the notion of "accuracy" is perhaps not the best thing to emphasize. Should the section "Don't sacrifice accuracy" be rewritten? What I would like to see the guideline convey is that Wikipedia articles should also strive to be serious encyclopedic reference works. While this need not be incompatible with the goal of making technical articles understandable, content should not be sacrificed in the name of making articles more understandable. That is, we shouldn't limit our coverage because some topics or parts of an article might be more technical than others. Sławomir Biały (talk) 20:47, 28 February 2011 (UTC)

Not sacrificing content is a somewhat separate issue. The injunction not to sacrifice accuracy, I think, is aimed at those who would like to tell

lies to children, giving readers an easier path to the feeling that they understand something, at the price of what they "understand" being wrong. --Trovatore (talk

) 20:54, 28 February 2011 (UTC)

Very good point. Perhaps this should be clarified somehow? On the "not limiting content" front, I was going to suggest that something along the following lines be added:

Don't limit content
Wikipedia strives to be a serious reference resource, and highly technical subject matter still belongs in some Wikipedia articles. Increasing the understandability of technical content is intended to be an improvement to the article for the benefit of the less-knowledgeable readers, but this should be done without reducing the value to readers with more technical background.

--Sławomir Biały (talk) 21:03, 28 February 2011 (UTC)

Em, this isn't any improvement on the text we have already. Colin°^Talk 22:08, 28 February 2011 (UTC)

I generally agree with Trovatore. The thing to avoid is writing like this article on the Poincaré conjecture, which tries so hard to be accessible that it both misses the entire point: it never says what the conjecture is. Put another way, we're writing reference articles, not popularizations. — Carl (

) 22:15, 28 February 2011 (UTC)

Would you care to draft a paragraph that makes this clearer than what is currently in the article? It doesn't sound incompatible with what I've written above. Sławomir Biały (talk) 22:20, 28 February 2011 (UTC)

Can we just make sure this remains a guideline on making technical articles accessible. The guideline on making a serious reference for maths scholars belongs somewhere else. I don't think it is helpful to litter this page with escape clauses and exceptions. Good writing is good writing and poor writing is poor writing. Just because someone trying to make an article accessible ends up writing a poor article on the subject doesn't mean we need a guideline saying "when you make the article accessible, avoid completely missing the entire point". Colin°^Talk 22:36, 28 February 2011 (UTC)

The point, which is very apropos for this guideline, is that "accessibility" is a goal, but not the only goal, and the level of accessibility we expect can vary from one article to another. We should keep in mind that Wikipedia is a serious reference for mathematics, already: this is one of the project's success stories. While everyone I know agrees that accessibility is also a goal, it would be a false success if we made articles more accessible by making them less useful as a reference. We can achieve both in many cases, of course, which is the ideal outcome. — Carl (

CBM · talk

) 22:43, 28 February 2011 (UTC)

To be fair, while I won't deny that our math content is likely considered reference grade approach, it is also a bain of trying to demonstrate how to write for a tertiary source; most other fields would not be able to go into such detail without crossing various

WP:NOT lines. I certainly am not suggesting we remove all the math kudzo from the work as that would be damaging for no reason, but we need to start these articles with "one level down" discussion of the meaning, importance, and use of such math aspects before they jump into the equations and proofs. Alternatively, we could consider how Wikisource or other sister projects could be used here, which is appropriate for detailed discussions on specific fields. So that's another thing to consider - can we split complex article to a tertiary source and then a textbook source and link them cleanly for advanced readers. --MASEM (t

) 22:51, 28 February 2011 (UTC)

I see no justification at all for removing advanced material to another project. --Trovatore (talk) 22:56, 28 February 2011 (UTC)

On the grounds that it's advanced? No. On the grounds that it's not an encyclopedia article any more? Sure. Wikipedia is not a textbook, even for mathematics. WhatamIdoing (talk) 23:00, 28 February 2011 (UTC)

Hmm. I thought Masem was talking about moving the pedagogical stuff to wikibooks. The reference material is what belongs here, since that's what a tertiary source should cover. Lengthy introductory material, numerous detailed examples, and such belong in a textbooks that our articles can simply reference. The main goal of a reference article is to provide the facts to people who have some idea what's going on and want specific info on a specific topic, or are looking for a good reference list for it. Articles that aim to popularize a subject or teach it from the ground up are more appropriate on another project. — Carl (

CBM · talk

) 23:07, 28 February 2011 (UTC)

Oh, sure, I would agree with that. --Trovatore (talk) 23:16, 28 February 2011 (UTC)

That's the idea but I've also seen cases which, I apologize, I cannot relocate immediately, in which every step of a derivation of an equation was reiterated in the WP article which did not help the "one level down" reader, who only cares to know what that equation was and how to apply it. This is not the best example but one I'm familiar with, Reynolds number, looking specifically at the "Where does it come from?" section. While correct, it's textbook to show each step in the conversion, when we can simplify it to two equations (the NavierStokes and the convert one), adding some "and then a miracle happens" in between, and yet still be completely appropriate for both advanced and less advanced readers. This is not as bad as I have seen elsewhere. Of course, this is not to say the steps couldn't be at WikiUniversity or elsewhere, just not on WP. --MASEM (t) 23:32, 28 February 2011 (UTC)

In mathematics articles we generally discourage detailed proofs, except when the proof itself is "notable" enough to have an article. I'm not sure that's an "accessibility" issue per se, though. --Trovatore (talk) 23:38, 28 February 2011 (UTC)

Well, to some extent it can be. While we have to be practical that people are using WP as a reference to learn information, we need to realize that a good number of people freak out mentally at a plethera of equations and symbols on a page. Even if we format the article properly, with a nice progression from general to specific, there will be people that see the equations and immediately avoid the page. Should we cave in to these type of people? Of course not, but at the same time, we want them to be comfortable reading the material. Thus when we start getting to math-heavy equations that really only help the advanced reader and would otherwise be covered in other sources or other sister projects it might be best to move them there. --MASEM (t) 23:43, 28 February 2011 (UTC)

It seems that there is even some content that hinders understanding by experts. For instance, detailed derivation often fail to convey the main ideas, which are the most important thing. Writing clearly and concisely is an important objective regardless of the audience. Should it be mentioned here? (In a general-purpose guideline like this, I think there is less that can be specifically said about articles in which long intimidating equations actually do belong.) Sławomir Biały (talk) 01:22, 1 March 2011 (UTC)

Not really. If there are key elements that are part of a proof that are crucial to its understanding, the points can be mentioned in a non-tech/formal presentation. Take again the Reynolds number example though a simple case. The key aspect is that the Navier-Stokes equation, when normalized by a certain quantity to make it dimensionless, produces the Reynold's number. You don't need to show every step, just say what we start with and what general maths are applied. Similarly, the article on the proof of Fermat's Theory introduces key ideas used but does not reiterate every step used. Is the article any less useful for advanced readers? No. Is the article more useful to less-advanced readers? Definitely yes. --MASEM (t) 01:28, 1 March 2011 (UTC)

Yes, I think that's what I'm saying. I'd be happy if something like this could be added to the guideline. Sławomir Biały (talk) 01:46, 1 March 2011 (UTC)

The issue of when to include proofs has been discussed a lot. Personally I think that full proofs should be included very rarely, essentially only when the proof itself is likely to be something people want to look up on its own or when it adds some essential insight to the topic. For most facts I think it's enough to just reference a good textbook that includes the proofs. — Carl (

CBM · talk

) 02:39, 1 March 2011 (UTC)

Apart from the issue of proofs, the common theme is that it is desirable to write clearly and concisely, emphasizing the main ideas as opposed to the minutiae of detail. Sławomir Biały (talk) 02:50, 1 March 2011 (UTC)

I strongly oppose any attempt to add, to this guideline, statements to the effect of "minutiae is not encyclopedic". The rationale for my position is that what is deemed to be minutiae depends on on the amount of knowledge an editor possesses. Wikipedia at present, does not have enough "expert editors" (my definition of which includes knowledgeable enthusiasts in addition to qualified practicing professionals). Therefore, if such a statement is included in the guideline, it is certain that we are going to see non-expert editors, either in good-faith or because they have an axe to grind, removing content for no reason other than they do not know of, or understand, the content's place in relation to accuracy and completeness (as determined by reliable sources), two quintessential attributes of a serious reference encyclopedia.

I expect that my rationale will be countered with an argument to the effect of "if a non-editor comes along and removes content that experts know is not minutiae, then it is the fault of the experts for not writing the said content to a level that is understandable to non-experts in the first place". I reject such arguments for two reasons. Firstly, what is minutiae has no correlation to accessibility. For instance, Pokemon trivia is easily understood by everyone, and perhaps even more so by children than adults, but it is still trivia. Secondly, such an argument assumes (and therefore is from ignorance) that it is possible to describe the topic in an accessible manner. Thus, removal of perceived minutiae may offend the editor(s) who wrote the removed content as it dismisses the value of their knowledge to the encyclopedia, leading to conflicts between the two editor groups, which is of no benefit to anyone. Rilak (talk) 04:01, 1 March 2011 (UTC)

Judging when you have crossed the line between important information and trivia or minutiae is not easy. I wouldn't want the guideline saying we must keep all minutiae either. Good writing knows what the essential points are and makes sure they are clearly stated (Sławomir's "emphasizing the main ideas as opposed to the minutiae of detail"). I've seen sections in technical articles that are full of detail, some of which is meaningless to a non-expert, where you really have to struggle to get the point. A good editor will know how to either extract the key points to the front of the text, or else perhaps write in such a way that the detail/hard stuff is parenthetical. The same information is present, possibly repeated, but a wider audience can understand it.

What I'd like to see the guideline doing is making positive suggestions about how to write accessibly while still including the necessary material to make it comprehensive and a good reference. Just saying "but be careful not to dumb down" or some such, is unhelpful. It doesn't help the writer and it looks much like a sop to editors unwilling to make the effort. To anyone who requests the material be made more understandable, they can simply reply "I don't want to dumb down the text". Colin°^Talk 08:54, 1 March 2011 (UTC)

Well, personally I don't support giving editors without sufficient background to understand the material a bigger stick with which to demand that the material must be made accessible to them personally, without them having to put in the effort necessary to understand it. When it can be done, it's a good thing to do it. But very often the ones complaining about it are not in a good position even to judge whether it can be done. --Trovatore (talk) 10:08, 1 March 2011 (UTC)

This is just a guideline and can't be used to "demand" anything. Of course the ones complaining about material being inaccessible are not usually a position to judge whether it can be made so. They don't understand the material. I don't see any problem with somone commenting that such-and-such isn't accessible to them. Responding sympathetically is something good editors will strive to do. Colin°^Talk 10:43, 1 March 2011 (UTC)

I agree with Trovatore's points. The system of creating daughter articles of ever-decreasing scope is ultimatly at odds with this guideline. Tony (talk) 11:31, 1 March 2011 (UTC)

Tony1, you make an excellent point.

WP:SUMMARY is an established, stable guideline that advises we create an inverted pyramid of articles with the simplest, most accessible summary article at the bottom and increasingly technical and detailed articles above. This guideline completely ignores WP:SUMMARY, and its fanatic-vibe-emitting assertion of "no reader left behind" is a major hindrance to editors trying to make articles higher up the inverted pyramid more accurate and complete (Macropedia-like). Rilak (talk

) 11:43, 1 March 2011 (UTC)

(ec) @ Colin: I strongly disagree with your opinion that this is "just" a guideline and therefore will not and cannot be used for nefarious purposes. The

WP:GNG

is just a guideline too, and look at all the drama it causes. While I obviously know that WP:GNG is for a very different purpose, there are similarities as to what these guidelines do: both "regulate" content, and both recommend removal of content if certain conditions are met. Notability is much different from determining minutiae and solutions to accessibility. Notability is much easier to determine without knowledge, that is, one can be a layperson, without understanding what a monograph is saying, and still be able to say, "I have found evidence of notability per coverage I found in these scholarly texts." This is not the case for this guideline. In fact, given the amount of drama WP:GNG produces, this guideline, if it were ever to include the aforementioned problematic clauses, will most likely produce more drama. And probably drama of a more vicious nature than what WP:GNG does when it pitches editors against fans of what is up for deletion, since this guideline can and will or does suggest an element of elitism on the part of the editors who wrote content deemed inaccessible. All we are going to get from such a guideline are laypersons complaining about inaccessibility and possibly making a mess of articles, and conflict with other editors, none of which furthers the goal of making what can be made more accessible, more accessible.

Regarding your assertion that good editors are editors who respond sympathetically to the complaints of readers, and the right of readers to complain about accessibility, I simply cannot see the relevance of both points to this discussion. Who is saying that complaints must be censored? And why should good editors be those who respond sympathetically to the complaints of readers? Am I wrong in assuming that what you mean is by writing, in response to a complaint, "Yes, I can feel your frustration, the article is inaccessible but there is nothing that can be done about it."? Or do you think that we should

charge at the solution-less "problem" until it yields

? Both are absurd for the reasons of lack of productivity and the lack of practicality, respectively.

Finally, I am curious as to what your edit summary of "why all the reader-hate". Can your please elaborate on it? Rilak (talk) 11:43, 1 March 2011 (UTC)

At the moment, this guideline does not say anything about removing material to achieve accessibility. Quite the opposite, in the "Don't sacrifice accuracy" section. I wouldn't support changing the guideline to suggest removing things that are "too technical", but at the moment it's not an issue.

The comment "I've seen sections in technical articles that are full of detail, some of which is meaningless to a non-expert, where you really have to struggle to get the point." is surely accurate, but I don't see it as relevant. Some technical articles will unavoidably have sections full of detailed material that a general reader may not care about, because that material is what a more advanced reader would want to find. "General readers" are just one audience, and their needs don't take precedence over other audiences. The goal is to serve multiple audiences. If you find a section you don't care about, skip it. — Carl (

) 12:06, 1 March 2011 (UTC)

There's a lot of good stuff in this discussion that I'd like to try to bring into focus. As I see it, the following points are significant and should be mentioned more explicitly:

• The guideline does not restrict the kind of content that can be in an article, but rather offers suggestions on how best to present that content so that it is understandable to a wider group of readers.
• As an idea for improved accessibility: try to summarize the main points clearly and succinctly before delving into details (if at all).

I do also feel like Tony's point should somehow be addressed, but I that has a less settled feel. Does this seem like a reasonable summary of things as they stand? Sławomir Biały (talk) 12:21, 1 March 2011 (UTC)

If Tony is talking about the "introduction to X" type of article, there has never been much consensus on that. Some articles of that type exist; others are merged into the main article, or deleted outright, like

CBM · talk

) 12:29, 1 March 2011 (UTC)

I think he is talking about how advanced content gets moved out to some other article in order to make one article more accessible at the expense of making another article less so. This is standard Wikipedia practice, though it is obviously at odds with a guideline that demands a uniform standard of accessibility. Sławomir Biały (talk) 12:32, 1 March 2011 (UTC)

I don't think that we can, or should, look for a uniform level of accessibility. Some topics are more technical than others, not just in math but in all areas.

CBM · talk

) 12:44, 1 March 2011 (UTC)

(e.c. with Slawomir) Eliz of Luxembourg isn't an overtly technical topic, so I'd be happy to gloss that item briefly, within commas or parentheses immediately after its first appearance possibly. Maybe a link too, but let's not encourage people to rely on links for basic definitions of words (rather, links should be for following up extra information).

There are two undesirables that a text needs to navigate between: too much clutter in explaining/defining items, and too little explanation (or unnecessary use) of technical items and jargon. Both of these undesirables need to take account of (1) where the topic lies in terms of the continuum from most broad to most narrow scope, and (2) opportunities to speak to a wider rather than a narrower readership if this can be done without disadvantaging the text.

The guideline should acknowledge that WP has articles over a range of scopes and in some cases addresses a more technical/expert readership. I think these balancing acts might be the basis of the guideline, although they are not easy to express clearly and succinctly. Tony (talk) 12:59, 1 March 2011 (UTC)

This guideline doesn't request a "uniform level of accessibility", though that is perhaps behind some of the problems people are imagining here. The nutshell said "Strive to make each part of every article as accessible as possible to the widest audience of readers". I quite deliberately did not write "Strive to make every article as accessible..." because that does imply some uniformity. The level of accessibility will vary throughout an article, but at each stage we should try our best. What's not to like about that? And why is this nushell still removed? Colin°^Talk 13:29, 1 March 2011 (UTC)

Further up, Carl says "The comment "I've seen sections in technical articles that are full of detail, some of which is meaningless to a non-expert, where you really have to struggle to get the point." is surely accurate, but I don't see it as relevant.". This is very relevant to a guideline on making articles understandable. If the information can be made accessible to a certain reader, why should they have to "struggle"? Often this sort of thing is the result of poor writing. A paragraph that is full of facts and figures but doesn't really have a point or a story to tell. Carl says the reader can skip the paragraph or section. Well perhaps they would and they would miss out on learning something. They don't have to read the article at all if that ultimately is the attitude we take. Please remember that all of us here have been students and are used to reading very advanced texts, skipping and skimming as requried. Please also remember that few articles on wikipedia take the maths approach of writing for other experts or students. Most technical subjects on Wikipedia are read by a non-expert reader, who won't have the patience and is just reading for enjoyment. Who reads our medical articles, our bird and fungus articles, our climate change and space rocket articles? Not (just) the experts. I would appreciate if the maths editors could tone down their defensive attitude and consider this guideline applies Wikipedia wide and hasn't been written to be a "big stick" to beat them with. Colin°^Talk 13:38, 1 March 2011 (UTC)

Colin, you are saying it between the lines. Advanced maths articles are likely to be read by maths students rather than the "average" reader (while there is no such thing). Anyway, the current guideline already addresses this with rules of thumbs such as "writing one level down". Nageh (talk) 13:45, 1 March 2011 (UTC) — Nevermind, I'm just seeing your note above that you do not propose a "uniform level of accessibility". Nageh (talk) 13:53, 1 March 2011 (UTC)

I want to say that I think including language along the lines of "Wikipedia does not aim for a uniform level of accessibility" in the main text would be very helpful to explain what this guideline is not promoting. --MASEM (t) 13:59, 1 March 2011 (UTC)

Summary style

Tony raises a point "The system of creating daughter articles of ever-decreasing scope is ultimatly at odds with this guideline." I assume he is talking about

rather than "introduction to X" articles. Does he mean the whole guideline, or just some part of it? Which part of it? What aspects of "creating daughter articles" is problematic here? I'm just not following the point at all.

Rilak is reading something into

that doesn't exist. Where does it say to "create an inverted pyramid of articles with the simplest, most accessible summary article at the bottom and increasingly technical and detailed articles above"? There's nothing in WP:SUMMARY about difficulty of material. It is merely one way of organising articles round a hierarchical approach. It works for some things but not for others. It is about how to sub-divide a big topic.

I agree with Carl that "introduction to X" articles are not a general solution. They seem to work for popular big topics. We can't turn everything into an "introduction to X".

When folk talk about this guideline being used "for nefarious purposes" and "a bigger stick with which to demand " something, can they point at which bits of this guideline text actually allows such behaviour. It isn't helpful to just say "this guideline is being used for...". Which bits are wrong in your opinion. Or should we just not bother making technical articles understandable. Or should there be an exception made for certain articles? Colin°^Talk 13:31, 1 March 2011 (UTC)

Nothing in WP:SUMMARY about difficulty of material you say?

From

WP:SUMMARY#Levels of desired details

:

Wikipedia is not divided into a macropædia, micropædia, and concise versions as is the Encyclopædia Britannica — we must serve all three user types in the same encyclopedia. Summary style is based on the premise that information about a topic should not all be contained in a single article since different readers have different needs;

* many readers need just a quick summary of the topic's most important points (lead section),

* others need a moderate amount of info on the topic's more important points (a set of multi-paragraph sections), and

* some readers need a lot of detail on one or more aspects of the topic (links to full-sized separate articles).

The parent article should have general summary information and the more detailed summaries of each subtopic should be in daughter articles and in articles on specific subjects. This can be thought of as layering inverted pyramids where the reader is shown the tip of a pyramid (the lead section) for a topic and within that article any section may have a

Main article: [[:<subpage name>]]

or similar link to a full article on the topic summarized in that section (see Yosemite National Park#History and History of the Yosemite area for an example using two featured articles). The summary in a section at the parent article will often be at least twice as long as the lead section in the daughter article. The daughter article in turn can also serve as a parent article for its specific part of the topic. And so on until a topic is very thoroughly covered. Thus by navigational choices several different types of readers get the amount of detail they want.

Is this clear enough for you?

On a side note, I wonder how long until the above quote to mysteriously "disappears" from WP:SUMMARY, given the sort of edit summaries along the lines of "why do you hate readers so much?" that I've been seeing in this talk page's history, and the constant refusals to include safeguards on potentially harmful aspects in this guideline. Rilak (talk) 03:15, 2 March 2011 (UTC)

I have no idea what you are talking about wrt quotes disappearing. Why quote it? I can read. There's nothing in the above text about difficulty of material. There's a lot of talk about the level of detail wrt to the topic/sub-topic/sub-sub-topic but detail != difficulty. The increase in detail is only wrt to the topic (due to the scope of parent/daughter/grand-daughter articles narrowing each time). The daughter article isn't necessarily a more detailed article in itself, just detailed when compared to the parent's coverage of the equivalent subject material. Is History of the Yosemite area a more difficult article than Yosemite National Park? No. In fact, it is possible that a summary section might be harder for readers to understand than the daughter article because it is so compressed.

Wrt the "reader hate" comment, it was a reaction to this. Do you think that is a sympathetic response to readers complaining they can't understand an article? I accept that "hate" was a poor choice of words, but it certainly isn't "love". That sort of negative attitude just doesn't belong here. We should be working out how to, you know, "make technical articles understandable". If that's not your aim, then what are you doing here? Colin°^Talk 08:54, 2 March 2011 (UTC)

Regarding the quote in question, it was intended as a humorous remark to certain "determined" people who "arrange" for the "disappearance" of "things" that "interfere" with their objectives. Since this guideline strongly pushes understandability and does not, and will not, discuss balance between understandability, accuracy, and completeness, it seemed appropriate to make such a remark at writing. In retrospect, it was in poor taste, given its subject matter, current events, its negative connotations, and it should not have been said. (And it failed to function as intended!)

Regarding the increased detail and increased difficulty, it is the case that WP:SUMMARY does not explicitly state that increased detail must mean increased difficulty. However, I don't think WP:SUMMARY was written specifically for technical articles, where I think it is a reasonable interpretation of WP:SUMMARY to mean that increasingly detailed technical information is inherently more difficult. So your example of Yosemite National Park is a poor example as a national park is not an intangible, abstract, difficult-to-visualize topic.

Regarding the diff, are you referring to responding to comments regarding article accessibility by saying something to the effect of, "I don't want to dumb down the article."? If so, I don't see the relevance to my position as to what this guideline to say, or to the position of other editors who expressed similar opinions. I am not saying that we should not make what can be understandable more understandable. My position on this guideline concerns its use of strong language, that in my opinion betrays the zeal that motivates it, and what potential side-effects the zeal will have on the balance between understandability, accuracy, and completeness. However, if you are insinuating that I would respond to comments regarding understandability in such a manner, you cannot be more wrong. I am not concerned with what ought to be so, I am concerned with what can be so. Responding to such comments positively or negatively is not an objective for me.

Finally, you ask me why I am here, participating in these discussions when I do not share your singular desire to have understandable articles. The answer is in the keyword "singular". You are writing and revising a guideline. A guideline effects the entire encyclopedia. It is essential that it maintains balance, that is, it works in harmony with other policies, guidelines, and unwritten established practices, so that in the end, it is of net benefit, that it is tolerant and accommodating of all reasonable positions. And for the record, if it is not clear to you, I am interested in increasing understandability, in addition to the accuracy and completeness of this encyclopedia. Rilak (talk) 09:38, 2 March 2011 (UTC)

Colin, please focus on the content rather than attempting to ascribe motives to editors. You have already ascribed incorrect motives to my own discussions here, and also tried in this same communication to discourage me from contributing to this page. This has not won you any points with me. Sławomir Biały (talk) 15:24, 2 March 2011 (UTC)

I agree, we should focus on the content. I did not try to discourage you from contributing to the page. On the contrary, I asked for positive contributions towards making articles accessible. It would greatly help if editors took a positive attitude towards developing this guideline. It would also help if people read the guideline and quoted the bits they thought were problematic rather than just making some general negative comment. Colin°^Talk 20:31, 2 March 2011 (UTC)

(I hate edit conflicts) Carl, I found the idea that you proposed on the math talk page of relating the importance (on the assessment scale) of an article with the desirable level of accessibility for a wider audience a reasonable guideline or rule of thumb (that we might want to include in this guideline). I don't think "Introduction to..." article are that bad of a solution for advanced topics that are still of interest to a wide audience (e.g., Introduction to general relativity vs. General relativity). (PS: Introduction to Global Positioning System was deleted because it was merely duplicating content.) Nageh (talk) 13:39, 1 March 2011 (UTC)

I think the way Tony is talking about it, this guideline potentially could suggest the use of simplified "Introduction to X" articles on a 1-to-1 basis with the technical article X, leading to excess content duplication, even if the content on one page is written completely differently and to a lower technical comprehension level, something strongly discouraged by SUMMARY and content forking. We should never have to create a separate article to explain a single topic at such a fundamentally lower level. Again, not explicitly stated here yet but advice that might be good to add to avoid it. --MASEM (t) 13:47, 1 March 2011 (UTC)

Dumbing down redux

Here is a new proposed section, to replace the "Don't sacrifice accuracy" section. This incorporates some ideas from the above discussion, explicitly including Trovatore's clarification:

Content and fidelity

Making articles more understandable does not mean that detailed technical content should be removed. Wikipedia strives to be a serious reference resource, and highly technical subject matter still belongs in some Wikipedia articles. Increasing the understandability of technical content is intended to be an improvement to the article for the benefit of the less-knowledgeable readers, but this should be done without reducing the value to readers with more technical background. It is also important not to oversimplify material in the effort to make it more accessible. Encyclopedia articles should not "tell lies to children" in the sense of giving readers an easy path to the feeling that they understand something at the price that what they then understand is wrong.

--Sławomir Biały (talk) 12:53, 1 March 2011 (UTC)

Here's my problem with this statement that is resonating above: We are a tertiary source, so there is no room for "detailed" content of any type - not just technical. We don't have scene-by-scene details of a creative work, we don't describe gameplay details of sports or video games to the minutiae, and so on, even in these cases the language can be made easy to understand by all. This, of course, is different from the phrase "highly technical". We should not be sacrificing "highly technical summarized content" but need to strip "highly technical detail content". I do appreciate that to someone not skilled in the technical content of such articles, there may appear to be no difference, and that this could create "layman vigilantes" that remove technical content - either summary or details - because they don't understand it, and such cases of course are not desirable. But those that are converse in the technical aspects need to use good judgement and aim to be a highly technical summary with reference links, sister project links, and other similar pointers to where highly technical details can be found.

There's more to just this to make tech articles understandable, by far, but it is a starting point - the more you summarize, the more likely you can inject additional language to explain terms or processes to "one level down" readers and increase the potential readership of the articles without making them, for lack of a better word, "stupid". It is difficult to do that when details are present. --MASEM (t) 13:38, 1 March 2011 (UTC)

I'm trying to summarize what seems to be the consensus of an earlier thread, which seemed to be that some minutiae were necessary for any treatment of a technical subject. But I am also sensitive to what you are saying (it is often necessary to summarize and remove overly detailed content, such as line-by-line derivations). A large part of this is just being knowledgeable and using good judgment. I'm not sure how both viewpoints can be accommodated. Sławomir Biały (talk) 13:45, 1 March 2011 (UTC)

@ Masem. The problem I have with your assertion that tertiary sources do not accommodate detailed of technical content is that once again, editorial freedom to adapt content to suit to the topic is being sacrificed on the altar of accessibility. Tertiary sources are one step down from secondary sources, which are themselves one step down from primary sources. But one thing that I notice in professionally-written secondary and tertiary sources is that when mind-boggling technical details happen to be necessary to having a summary that makes sense (not lie-to-children-sense), authors do not hesitate to embrace it. Rilak (talk) 03:04, 2 March 2011 (UTC)

Line by line derivations are rarely added in math articles anymore. There are many remaining from the early days, but with 20,000+ articles we can't easily edit every one. There's not unanimity, but most math editors seem to think that most detailed derivations can be omitted without making the articles less useful as references. — Carl (

CBM · talk

) 13:48, 1 March 2011 (UTC)

I think, ultimately, besides some basic language, it can be accompanied by do/don't examples: eg, don't include full proofs but do summarize it.

But another thing that can be included is that since we are a reference work, we should mimic what level of detail most other references works in that field take. In nearly all of our chemical compound articles, a wide array of physical and chemical properties are given. This could be taken as details, but when you consider most chemistry reference works, these are simply quite common, so would seem to be appropriate part of a summary of them. If we're talking metals and alloys, sheer stresses and moduli would make sense, and so forth. --MASEM (t) 13:53, 1 March 2011 (UTC)

@MASEM: The difficulty with summarizing and adding additional language, of course, is that it is very easy to put in original research that way. Under even moderately strict interpretations of the OR policy, we can't add new analogies, explanations, or examples if they can't be literally sourced somewhere. But if all the references in an area are specialized, they won't include analogies or explanations suitable for an unprepared reader. They may have no examples at all, if the examples are easy to come up with. So there's a narrow line to walk. — Carl (

CBM · talk

) 13:48, 1 March 2011 (UTC)

Sure, I can appreciate that some topics cannot be simplified down without either potential OR introduction or the mangling of the English language to get it there. All I'm saying is that if you start from the summary level as opposed to the detailed level, you have a better likelihood to find language to help comprehension. But I totally agree that we shouldn't break our founding principles to make technical summaries easier to understand. --MASEM (t) 13:56, 1 March 2011 (UTC)

Masem makes an important point. Encyclopaedias summarise information. There is a point where we aren't doing that and have become equal in detail to the material we are drawing from. The "serious reference resource" goal has the same dangers as the "sum of all human knowledge" lie -- if folk take it as fundamentalist gospel, they forget we're writing an encyclopaedia. But I'm not sure that the editorial judgement decision of how detailed or how much detail to include, is a problem for this guideline. Seems more suitable for

WP:NOT. Colin°^Talk

14:46, 1 March 2011 (UTC)

I generally take "encyclopedia" to be a synonym for "serious reference resource". Our goal is not to emulate Britannica in giving extremely shallow coverage of advanced topics; we already far surpass them in our coverage of many areas because we don't limit ourselves to make every part of every article accessible to everyone. Try to find material on group theory in Britannica, for example; it's just not there apart from a vague paragraph in Fermat's biography.

On the other hand, the main way to increase accessibility is to go into more detail than the sources, not less. This guideline asks us to to explain things in greater length and to include more analogies and examples than an advanced reference would. The articles that people often complain about are ones that do simply summarize the existing sources without trying to add pedagogical material.

So we have to pick our poison: do we want something that simply summarizes the references, but doesn't interpret them? Do we want something that attempts to teach the subject to someone who has no background? We try to do both when possible, but each one has its place, depending on the topic of the article. — Carl (

CBM · talk

) 15:04, 1 March 2011 (UTC)

No, we shouldn't be teaching, that's what WikiUniversity is for. The numerous sister projects of Wikipedia can all be used to go and give deep details about technical topics, but Wikipedia itself needs to stay as a tertiary source across all fields and provide summary of sources with no novel interpretations of materials. --MASEM (t) 15:28, 1 March 2011 (UTC)

There's a difference between adding finer detail on the topic and just adding information so that someone can understand the topic. We can't go "more detailed that our sources" (that would be OR) but we can supply more information than some of our most advanced sources tend to do. I don't know about maths, but in other fields that may mean using a variety of sources at different levels (papers, scholarly monographs, student textbooks, for lay-reader texts).

I disagree that making technical stuff accessible requires "pedagogical material" or "teaching", which we shouldn't do. Again, maths may differ. Merely explaining that "hypotension" is "low blood pressure" isn't teaching someone medicine. Colin°^Talk 15:40, 1 March 2011 (UTC)

That's certainly true for hypotension. The opposite situation is articles like

CBM · talk

) 16:01, 1 March 2011 (UTC)

I want to emphasize I do wish that

CBM · talk

) 16:26, 1 March 2011 (UTC)

The "without specialist knowledge" requirement is peculiar to primary source material. Colin°^Talk 16:41, 1 March 2011 (UTC)

That's true, but: (1) Editors at WT:NOR often argue that research papers are primary sources; and (2) even for secondary sources, editors often complain about "synthesis" when the claim in the article can't be directly seen in any particular source. The sort of writing that people would normally do to make an expository article would be "synthesis" in the OR policy. Which isn't surprising, because all writing requires some degree of synthesis.

I looked up the Birch/Swinnerton-Dyer conjecture in the Princeton Companion to Mathematics, and that is slightly more accessible to a mathematician (probably still not to a general reader). It would be a good source for the article. However, the layout the Princeton companions was different than our required layout, and the phrasing they use would would run into issues here (like WP:PEACOCK). — Carl (

CBM · talk

) 17:20, 1 March 2011 (UTC)

Why are you using research papers as a source? What benefits do they have over other sources in mathematics? Our policy says articles should be based largely on secondary sources. As for "synthesis", I wonder if there is (or should be) a difference for material that is incidental/helpful compared to material that contains the key facts. But this is straying into discussions that probably belong on other pages. Colin°^Talk 18:37, 1 March 2011 (UTC)

I doubt that the "NOR regulars" would be very amenable to language that tries to make a distinction between key facts and incidental ones. My point is that we don't have as much freedom in coming up with an "accessible viewpoint" if that viewpoint is not already represented in a source. This is a particular trouble for topics whose only sources are advanced. — Carl (

CBM · talk

) 18:57, 1 March 2011 (UTC)

Scope of the guideline

I feel as though something like the following should be added, perhaps as a section separate from the "Rules of thumb". This expands on some of the earlier discussions in this thread:

Technical content

Wikipedia strives to be a serious reference resource, and highly technical subject matter still belongs in some Wikipedia articles. Increasing the understandability of technical content is intended to be an improvement to the article for the benefit of the less knowledgeable readers, but this should be done without reducing the value to readers with more technical background. Making articles more understandable does not necessarily mean that detailed technical content should be removed. For instance, an encyclopedia article about a chemical compound is expected to include properties of the compound, even if some of those properties are obscure to a general reader. But often summarizing highly technical details can improve the readability of the text for general readers and experts alike. For example, a detailed derivation of a result is unlikely to be read by either a general reader or an expert, but a short summary of the derivation may convey a sense to a general reader without reducing the usefulness to an expert reader. When trying to decide what amount of technical detail is appropriate to include, it may be helpful to compare with a standard reference work in the particular technical field to which the subject of the article belongs.

In addition, the "Don't sacrifice accuracy" rule of thumb can be replaced with:

Don't oversimplify
It is also important not to oversimplify material in the effort to make it more accessible. Encyclopedia articles should not "tell lies to children" in the sense of giving readers an easy path to the feeling that they understand something at the price that what they then understand is wrong.

--Sławomir Biały (talk) 20:55, 5 March 2011 (UTC)

I tried to remove a bit recently added about examples needing to satisfy

) 14:01, 1 March 2011 (UTC)

For example in

) 14:10, 1 March 2011 (UTC)

I've removed it for now. Since there seems to be a perennial confusion of how

WP:V applies to examples, it seems safest to leave it out. Thanks, Sławomir Biały (talk

) 14:13, 1 March 2011 (UTC)

I think "perennial confusion" is about right. A different way to understand it is that some people really do want to avoid any novelty whatsoever, even just rephrasing something in different words. Other people would be fine with any sort of example as long as someone with knowledge in the area could verify it. In reality we aim somewhere between these extremes, and it generally works OK in articles, even though people don't agree about it on the policy pages. — Carl (

CBM · talk

) 14:20, 1 March 2011 (UTC)

Thanks for bringing this up. In fact, this is giving me one of the major headaches when writing technical articles. Yet, it is part of a bigger picture:

) 15:40, 1 March 2011 (UTC)

If your explanation is accessible to the reader (or, more pointfully, the complaining editor) and your example is true to it and actually illustrates the explanation, then the editor ought to be able to determine that they match. Consider the statement "children should be able to add double-digit numbers without

as obvious as the color of the sky. WhatamIdoing (talk

) 02:58, 5 March 2011 (UTC)

Layout and lede

I looked up Birch and Swinnerton-Dyer conjecture in The Princeton Companion to Mathematics. Their article is much more accessible than ours (and much more accessible than the official problem statement by Andrew Wiles, although that is not intended to be particularly accessible). However, they achieve this by using a different layout than we do. Instead of beginning with an overall summary of the topic, the Companion starts by talking about elliptic curves, then about the group of rational points, and only gets to the conjecture later.

We can't do that here, because

) 17:29, 1 March 2011 (UTC)

I was hoping someone would say something about examples. The solution is simple: use up the four statutory paragraphs, and simply continue the discussion (with examples!) in the first section entitled, for example, "introduction". Tkuvho (talk) 17:50, 1 March 2011 (UTC)

What if four paragraphs don't even get you to the topic of the article? That would be a common way to write expository material: you start with some background and motivation (one or two paragraphs), then some immediate background definitions (another two paragraphs, say), and only then do you start talking about the actual topic. In our articles, one source of inaccessibility is the fact that we are required to start talking about the topic from the first sentence. — Carl (

CBM · talk

) 18:54, 1 March 2011 (UTC)

There's no need to have four paragraphs of lead. The change Carl made today was a big improvement to the lead and an example of putting the accessible stuff up front. Even if I have no idea what the conjecture is about (and I probably won't, ever) I can understand its importance and some aspects of it (that it hasn't been proven, generally). The second paragraph loses me but if this is a decent two-sentence summary of the topic, then I suppose it is reasonable to expect that in the lead. That's a fairly small amount of material to have to skip (if I had to skip three paragraphs of the stuff in the lead, I'd give up) and the first body section starts off in English, which is a promising sign :-). So I don't think the lead is the problem with that article, and if the body can be improved along the lines suggested by that other source, then good. Colin°^Talk 19:43, 1 March 2011 (UTC)

I think it's important to remember that the "four statutory paragraphs" are not an absolute limitation. If you need five paragraphs, use five. If you need just one, do that instead. LEAD is a guideline, and must be implemented with common sense and the

occasional exception. A large and highly technical subject is reasonable grounds for making an exception. WhatamIdoing (talk

) 03:02, 5 March 2011 (UTC)

Conflicting guidelines and revising

WP:LEAD

I second Carl's suggestion for revising the lede guidelines when there is a conflict between accessibility and comprehensiveness. The preference should be given to accessibility. Tkuvho (talk) 05:52, 2 March 2011 (UTC)

I'm sympathetic to the issue, but I'm not sure that the current

WP:LEAD

to summarise the topic. And surely the expert reader will expect to see a short precise description of the conjecture in the lead -- he'd be disappointed if the lead only told him that it was important and unsolved.

Maybe Exterior algebra is a better example. Trying to produce a condensed form of the body might actually make the lead harder to follow than the body. What aspects of a difficult body would we keep and what might we simplify when summarising? How do we express that in a guideline?

Perhaps Angiomyolipoma has an example. See earlier in the talk page for examples of alternative lead sentences. Most of them concentrate on the classification. But the classification is a really difficult thing here because the terms used are probably foreign even to most doctors. So the lead of that article isn't a full summary of the body and the classification has been simplified in the lead to just "benign tumour". Is this the sort of thing we are saying when we might simplify or eliminate material from the lead in an effort to be more accessible? Colin°^Talk 09:11, 2 March 2011 (UTC)

An idea for topics which cannot be described in language "one level down" without mangling the idea, resorting to similes/metaphores/examples, or the like, might be better to avoid trying to describe what it is and instead focus on the why or how aspects in the lead. The body is fine to describe what the topic is about at the appropriate summary level for that topic.

For example, the lead of Fermat's Last Theorem, beyond a few points here or there, get to the why of this rather quickly - it gave birth to a new branch of mathematics. It's not a perfect example but notice how it sidesteps the critical math elements later given in the body. Something similar should have to happen with Birch and Swinnerton-Dyer conjecture (I have no idea why this is worth a $1M prize for a proof). --MASEM (t) 17:34, 2 March 2011 (UTC)

Good idea. In general, such explanations could be given in terms of established theories for which a given concept is a basic building block. For example, at de Rham cohomology and Hodge theory, the leads are pretty sparse but could be amplified by mentioning the significance of these for other fields of mathematics. What is entirely missing, though, is a bit of an explanation of the basic concepts. Here one could elaborate what happens on the case of the circle and also in the case of tori or more general surfaces, to give an idea of the general theory. This sort of thing is not going to be a summary, and it is not going to be comprehensive in any sense, but it will be useful for the reader nonetheless, more so than an "impacted" summary of the article (to borrow a term used by Matthews in the recent interview--I hesitate to use the "B"-word). Tkuvho (talk) 17:45, 2 March 2011 (UTC)

Just want to say that this sort of discussion on how we can deal with a difficult lead for a difficult subject is exactly why restoring this page to guideline status was so important. We simply couldn't have this discussion on

09:04, 3 March 2011 (UTC)

I'm not sure where a good place to add this is, so I'll just say it here. I think that the lead should still attempt to summarize the key points of the article. I don't think that an exception to

WP:MTAA#Lead section paragraph of this guideline already says what needs to be said. There is bound to be some conflict between this guideline and the need to cover technical material. The lead of an article is meant to be read by everybody: that includes not only people with limited background, but also those with more extensive background. While technical details shouldn't be given in the lead ("only summarize"), we still need to make an effort to summarize the key points of the article. Sławomir Biały (talk

) 15:16, 5 March 2011 (UTC)

I agree. The lead should serve both as a summary of the article and an introduction to the topic, and

Shapley-Folkman lemma

).

If the task of summarizing the article and introducing the topic concisely in the lead proves impossibly difficult, then there is a solution available: a spin-out article, as in

summary style. This is a technique we readily use when other sections of an article become too long and detailed. Similarly, "Introduction to..." articles (and the like) effectively provide summary style spin-outs for the introductory role of the lead. As with summary style, and as indicated in the present guideline, this should not be done unnecessarily: if the problem can be fixed by improving the lead and/or body of the article, do that instead. Also, the existence of an introductory spin-out is not an excuse for making the lead less accessible. Geometry guy

16:08, 5 March 2011 (UTC)

Actually, a good example of a place where I had a hard time writing an informative lead, and eventually gave up was extensive-form game. If you look up the topic in textbooks, there are two approaches: the math-undergrad or econ-grad approach is to smack you with definition (which in some books is spread on several pages!) and then give some examples. The gentle approach is to spread the whole thing over several chapters and intersperse it with the normal-form game discussion for the same game types. (Yeah, I know the article needs a lot of work to better present results, not just the def and examples.) Tijfo098 (talk) 15:31, 28 March 2011 (UTC)

Should there be a guideline on using jargon or technical language in section titles? This came to my attention when I noticed most "Bird" articles have sections titled "Taxonomy". It's a word that stops you (well me) dead - so whats this section about? It seems to be contrary to every part of this guideline. When jargon/technical language is in a section title you can not explain it when its first used (without creating a very long title), or even wikilink it. None of the articles bother to do either, the word is not brought up again. The "section" definitely does not "start out understandable". I brought this up at Wikipedia talk:WikiProject Birds#Taxonomy? but I noticed (and several other editors pointed out) this goes on project wide with words like "Pathophysiology", "phylogeny", etc. being recommended by their relative project pages as title MOS. It seems to me if there is a precise word that covers many aspects, it's a clue to break it up and have sections with common titles for each of those aspects. Ohioartdude2 (talk) 13:33, 11 July 2011 (UTC)

This is only a problem if you are unwilling to learn the meanings of such words. Taxonomy, pathophysiology and phylogeny are pretty common and standard technical terms in their respective fields, whose inclusion in your passive vocabulary is not going to hurt you. In the same way that one learns how Wikipedia works (even for readers), i.e., things such as the difference between articles, disambiguation pages, lists, categories, project space, etc., different kinds of links in different parts of the page, etc., in just the same way one learns about these terms just by the kind of stuff that can be found in the sections headed by them.

That' s not to say that these terms should not be replaced by 'easier' terms where available. But they are certainly preferable to misleading or roundabout circumlocutions, merging sections to avoid 'bad' words, or other, similarly invasive avoidance strategies. I am not sure that we need written guidance about this, as it's basically just common sense. Hans Adler 15:06, 11 July 2011 (UTC)

Learning about words is fine although Wikipedia is nether a dictionary nor an instruction manual to teach words. I wouldn't say avoid 'bad' words, just explain them per this guideline. You can't do that in a section title. Reliance on technical words in a section heading (or anywhere else in an article) point to problems in encyclopedic editing, the article has not been boiled down to the level of the "average reader" yet. Recommending such words as titles in an MOS kind of perpetuates this problem. Ohioartdude2 (talk) 16:28, 11 July 2011 (UTC)

"Taxonomy" is not a technical term. It is a term that has passed into regular English usage. Most educated people know the meaning of this word, without any specialized instruction in biology. Sławomir Biały (talk) 12:47, 13 July 2011 (UTC)

Many differ with that statement[3][4][5][6][7]. Ohioartdude2 (talk) 20:41, 20 July 2011 (UTC)

The first link includes in its banned list words like "advocate", "agencies", "capacity". Several of the other links just show that there are many illiterate people online. I'm not even sure what relevance a "web design glossary" has to this discussion. If this is the best you can do, I'm really not impressed. (In fact, according to your first link "can do" is a banned phrase... I guess I am not allowed to use that either). I am a mathematician with no specialized training in biology, medicine, philosophy, or religion. English is my second language. I know what all of the words under discussion mean: etiology, hermeneutic, phylogeny, taxonomy. These are not jargon: they are regular words in the English language. Just because they may not be included in some less educated people's vocabulary doesn't make them jargon. "Gregarious", "obstreperous", "lugubrious" are words that many uneducated people don't know, yet they are not jargon. If you see a word you don't know, look it up in the dictionary. This isn't dummipedia; we have simple English Wikipedia for people who prefer an encyclopedia written for audiences lacking an educated vocabulary. Sławomir Biały (talk) 13:00, 28 September 2011 (UTC)

This is getting a bit ridiculous if we're arguing that etiology, phylogeny, and hermeneutic are everyday words that should be used instead of more straightforward alternatives. (No one knows what hermeneutic means. Seriously.)

--Qwerty0 (talk) 18:48, 28 September 2011 (UTC)

Actually, nevermind this. We're both obviously arguing from principle and claiming more than is reasonable for this particular discussion. You're worried about "dumbing down" Wikipedia. I'm worried about keeping it useful for non-experts. But really, there's bigger fish to fry than this section heading thing.

Let's wait till there's a more important dispute and discuss its merits instead of using this one as a proxy for our cause.

--Qwerty0 (talk) 19:32, 28 September 2011 (UTC)

First, I recommend that anybody discussing this look a bit at the bird project discussion, to see what some editors in biology, the subject this is concerned with, think. I guess a big part of the argument that I and others made is that there's nothing better to use than taxonomy, as Hans Adler put it, the alternatives are "misleading or roundabout circumlocutions".

Where is 'phylogeny' recommended? Not at any vertebrate projects, as far as I know. (I would think this would always go under 'taxonomy', or a (sub)section named something like 'evolutionary history'.) For the links, I don't see what Google shows, the last three sites largely discuss different meanings in more specific subjects, not the general meaning of the word or its use for biology, and these are in rather different contexts—alternatives are much more appropriate in the context of the local governments documents the BBC discusses. None of this demonstrates that the term is not widely understood (not that I can find anything to the contrary). —innotata 17:45, 22 July 2011 (UTC)

Hmmmm.... there are allot of words that are useful and specific. The problem is, are are not very useful in an encyclopedia - hence this WP:MTAA guideline. A word that is explained some 119,000 times [8] is probably jargon/technical and therefor not very useful in an encyclopedia. I wouldn't say there needs to be "roundabout circumlocutions" to get around a word. If one word is covering allot of things it is probably a sign that the article needs further breaking down to cover those many things. Ohioartdude2 (talk) 03:30, 24 July 2011 (UTC)

With all respect, but "taxonomy" is such a common word in any science field and has entered regular usage indeed (read some newspapers!), that seeing such a trivial word explained to me in a general article I would perceive as an affront. There will always be people who do not understand "difficult" words: you may replace your example with any other, e.g., a Google search for "What is filibustering" "filibustering is" claims 24,800 hits as well (and I did not look for any other words). That does not mean that we would have to explain "filibustering" in any article on a political topic, even though we have articles on both

filibustering. Nageh (talk

) 10:46, 24 July 2011 (UTC)

Since "classification" would communicate the same idea to the educated reader as "taxonomy", I'd choose that more familiar word—just like I normally choose "mechanism" instead of "pathophysiology", and "cause" rather than "etiology", even though I think that any college-educated native English speaker(!) should understand all of those words. When we can easily make the text accessible to less-educated readers (i.e., without introducing errors), then IMO we should do so. Using the fifty-dollar word instead of the fifty-cent word often strikes me as showing off how smart (we think) we are. WhatamIdoing (talk) 21:09, 25 July 2011 (UTC)

^THIS^

Hope this discussion's not too old, apologies if so. Just wanted to weigh in that the general idea of "using the fifty-cent word instead of the fifty-dollar word" is really crucial.

Honestly, whatever about the "taxonomy" ting. There are way more pressing issues. I kind of expect to not understand many section titles. But it's a good example of a time when there's a perfectly good alternative that isn't an unnecessary obstacle thrown at non-experts.

I'm a biologist, so of course "taxonomy" is an everyday, uneventful word for me. So it took some effort to shift my perspective, remembering how it is for me trying to navigate a math, medical, or art article with section titles like

Hermeneutics of religion. Even a word like Etiology I have to stop to look up. And it's in a field related to biology! So I realized: Ok, yeah, maybe it's not a trivial thing to make it so my mother doesn't have to search through the whole article when she's just looking up a bird to see what it's related to. This sort of thing happens. It recently took me hours perusing DNS

to find the distinction between registrars vs. registries.

Anyway, opaque section titles are often unavoidable. No big deal. But when there's an available alternative like "Classification" that's more straightforward for non-experts than "Taxonomy," why not use it?

--Qwerty0 (talk) 09:52, 28 September 2011 (UTC)

These two shortcuts lead to two different places.

) 13:05, 4 April 2012 (UTC)

Importance of "Introduction to " articles

What level of importance should be given to "Introduction to" artciles? Should the level of importance be automatically related to the importance level of the parent artcile? If so, the same level, or a lower level? Martinvl (talk) 09:16, 13 October 2012 (UTC)

Is this about the

WP:1.0 team's assessments? WhatamIdoing (talk

) 00:37, 16 January 2013 (UTC)

Prerequisites Project

Please express your opinion on the Prerequisites Project suggestion. Editingeddie (talk) 15:25, 20 May 2013 (UTC)

As wikipedia becomes more and more popular and respected, the introduction and writing style of articles becomes more and more convulted and difficult to understand. Examples include Domain name ^{(my edit} and Phoneme.^{(my edit)} Zeddocument (talk) 11:23, 11 June 2014 (UTC)

Why does a page describing the need for more understandable writing feature strained verbiage like "do not provide such a quantity of locutions as to impel those who aspire to derive serviceable information from the article to consult a dictionary or thesaurus"?

) 20:27, 1 January 2016 (UTC)

Probably this "irony" thing I keep hearing about. (On a more serious note: occasional light-hearted injections probably do contribute to better readability.) Markus Pössel (talk) 08:38, 2 January 2016 (UTC)

I fail to see how. Switching mid-paragraph from a formal, just-the-facts tone—as expected on Wikipedia—to a jocular one is just confusing. If indeed the passage cited is meant as a joke, then it falls flat. I consulted this page for help with editing articles, and the irony is not helpful. —

talk

) 20:15, 8 January 2016 (UTC)

Can't the guideline be simplified to "make articles understandable"? --Ilovetopaint (talk) 10:29, 22 March 2018 (UTC)

I don't think that people complain much about well-developed biographies or other non-technical subjects. WhatamIdoing (talk) 05:58, 3 September 2020 (UTC)

I just added a note in the "Avoid overly technical language" section, "Preface explanatory sentences with caveats..." ([9])

In order make sure that articles as a whole are complete and precise, editors should preface any brief explanatory sentences (when a less complete or precise explanation is given) with a phrase such as "Generally..." or "With some exceptions.." so the reader knows that there is more complexity behind the explanation. The brief explanatory sentence(s) should be followed up with more detail, or the article can include a "robust definition" section so that the article as a whole is complete and precise. Sparkie82 (t•c) 03:17, 14 October 2020 (UTC)

Proposal:

I offer some new text for the section titled "Lead section" to be inserted after the following sentence in the third (and last) paragraph:

"In general, the lead should not assume that the reader is well acquainted with the subject of the article."

Followed by this proposed text:

"Terminology in the lead section should be understandable on sight to general readers whenever possible and should not depend on a link to another article. Any link to another article should be a supplement to provide more information, and preferably should not be required for understanding text in the lead."

My proposed text continued:

"Exceptions to this practice may be necessary for highly technical subjects, such as mathematics, medicine and hard sciences, but even for those topics, editors should make every effort to use ordinary language and put the unfamiliar technical terms and their definitions in the body of the article, with links to other articles as appropriate. If a specific term is easily understood and also linkable to an article, it can be linked from the body of the article, not from the lead. The goal is a lead section with either a bare minimum or no linked terms (except things like names, locations, events), offering a smooth reading experience with no need to repeatedly stop and hover or click to learn the meaning of a word or phrase."

But that's kind of long, though I'd be happy to see it included as well.

I would prefer to eliminate the last sentence in the section, which now reads: "For highly specialized topics where it is difficult to give an overview in terms with which a general audience will be familiar, it may be reasonable to assume some background knowledge in the lead while linking to the prerequisites required to understand it."

Rationale:

I browse Wikipedia a lot, and I do zillions of Google searches about all kinds of things, and of course, a Wikipedia entry is nearly always on the first search page and often the first item. I am all too often disappointed and frustrated to see a reader-unfriendly snippet with dense, jargon-filled language (and larded with links) in the search results, or when I browse to an article on the site and see an opening paragraph like that.

An example is an article that looked like this [10] when I first encountered it. With my encouragement and some collaborative editing, the article now looks like this: [11]. Some links remain in the lead, but they are terms a general reader can easily understand without reading the linked text. There is no shortage of articles in which the lead needs to be transformed like Tidal Locking was to become useful to general readers. By incorporating the text I've suggested, we can add a little more fiber to this Guideline to help us prevent or repair such prose. DonFB (talk) 05:24, 27 July 2021 (UTC)

When I read that old revision of Tidal locking (which, btw, you did a great job improving!), I see multiple problems. Yes, there are too many technical terms, but there's also the issue that it tries to start with a fully general definition (rather than one that's less robust but easier to understand), and that it takes too long to get to an example. I'm not convinced we need to specifically call out the issue of technical terms when talking about the lead section - though I don't think the proposed text constitutes bad advice by any means. Colin M (talk) 20:02, 27 July 2021 (UTC)

I think there's much to like in DonFB's text, especially the point that links are not a substitute for making oneself clear. That's a point that can't be made too frequently across Wikipedia in all sorts of contexts.
That said, I think Don overestimates the extent to which highly technical topics can be rendered in generally understood phraseology. The understandability requirement must never become an upper bound to the difficulty of the material that can be treated in Wikipedia. That's why I've offered a small change to Don's text. (Obviously I very strongly disagree with the suggestion to remove the last sentence.) --Trovatore (talk) 19:31, 5 December 2021 (UTC)

"If you can't explain it to your grandmother, you don't really understand it"

Whether Richard Feynman, Albert Einstein, or Earnest Rutherford said it, it really answers the question of whether "highly technical topics can be rendered in generally understood phraseology". They can. Feynman's physics text for first year college students, the Feynman Lectures, explains ferromagnetism, the electromagnetic mass of the electron, derives the Navier-Stokes equations, and his own Nobel prize work on the variational principle of quantum mechanics, all in understandable form. Stephen Hawking, whose work only a tiny fraction of physicists can understand, wrote a general interest book about it without a single equation that became a bestseller. And these were experts who didn't have any experience writing for general readers, like we do. Youtube is full of 5 minute videos explaining the most high level, esoteric technical concepts in a way comprehensible to high school dropouts (I'm not saying these are all good, or accurate, or that Youtube should be relied on as a source, but many are good). Same with TEDtalks. Take a look at Britannica's articles, they are wonderful. If Wikipedia's technical articles are not comprehensible to general readers (and a lot of them aren't) we're not trying hard enough.--Chetvorno^TALK 00:32, 12 December 2021 (UTC)

That's one of those commonplace sayings that sounds good, but is — I can't possibly say this strongly enough — simply flat wrong. The actual situation is that there are any number of things that you can't explain with any reasonable level of fidelity without first teaching the listener a graduate-level course on the background of the subject. --Trovatore (talk) 06:40, 13 December 2021 (UTC)

I support DonFB's first paragraph. I don't really think the 2nd paragraph is needed. I loved your example of the Tidal locking article! A perfect illustration of the common WP problem of an introduction that has been abstracted to incomprehensibility by compulsive wonks. --Chetvorno^TALK 00:32, 12 December 2021 (UTC)

Well said, and glad to see that another editor shares my feeling about article introductions that are "abstracted...wonks". DonFB (talk) 05:44, 12 December 2021 (UTC)

This is a real problem; I don't want to minimize it. Articles should be written as understandably as they can be, given the inherent nature of the subject matter. And many times they are not written that way. Nevertheless there is material that can and should be treated in Wikipedia, that cannot be explained to a general readership in any useful way. --Trovatore (talk) 07:21, 13 December 2021 (UTC)

Modifying my opinion above. I have no objection to linking words in the lead. But the lead should not rely on links to explain technical terms. Any jargon terms should be explained in the lead, and readers can follow the links if they want additional information. --Chetvorno^TALK 20:54, 12 December 2021 (UTC)

To the extent that they can be, yes, I agree. But there's a limit to the extent that they can be, without rendering the article useless.

I think writers should strive to write the lead to be understandable by readers one to two levels less specialized than the subject matter of the article. Say, measurable cardinal should be written so that readers with a basic understanding of mathematical logic and set theory can work out what at least the first paragraph is saying. Can they as it's currently written? I would say they probably can, though the first paragraph is written too much as a definition, with not enough indication why anyone should care about the subject of the article.

Can it be written so your grandmother understands it? Could be, if you have a very unusual grandmother. But no, it can't be written so that a general readership will know what you're talking about, not without writing so much background information that you would never actually get to the subject of the article in a reasonable time. --Trovatore (talk) 07:33, 13 December 2021 (UTC)

Well, okay, maybe not the entire introduction, but at least the lead definition or paragraph should be explained in language that most readers could understand. I'm convinced this is possible for even the most advanced articles. I spend most of my editing time rewriting STEM articles so they are more comprehensible by general readers. A lot of times what ordinary readers want to know from the intro is not "how does this work?" but "what is this called in ordinary language? what does it look like? who uses it? how is it applied? what field is it in? why is it important? We just need to put ourselves in the ordinary reader's head. --Chetvorno^TALK 23:31, 13 December 2021 (UTC)

I don't see that your example of the current

transfinite cardinal

is. I have a BS in electrical engineering, and I wouldn't know what it is except I've done additional reading. I would say this is a good example of an introduction which could be made minimally understandable with a few additional sentences:

"A

natural numbers: {0, 1, 2, 3...} There are infinite sets that have more members than the set of natural numbers, such as the number of points on a line, so this is represented by a different cardinal, C. A measureable cardinal represents a set, finite or infinite, that has certain properties that allow the "size" of subsets to be defined sensibly; for example the points on a line segment have the property that a subset of a line segment has a shorter length than the segment itself, and a line segment that is divided into two segments has a length that is the sum of the lengths of the two segments. These and other properties allow the "length

" measure of a line segment to be defined. So C is a measureable cardinal."

Okay, my grandmother couldn't understand that, but someone who has been exposed to elementary set theory, such as high school graduates who have taken algebra or geometry, could. As you say, there should also be something on notability, why anyone should care. I'd say the above would satisfy your condition of writing "down" two levels. --Chetvorno^TALK 23:31, 13 December 2021 (UTC)

Well, the fact is, what you've written isn't correct. I'm not saying that to shame you — it would be really hard to understand it well enough to write something correct without having taken at least an advanced undergraduate set theory course.

But let's say arguendo that you could write something in that general tone that is correct. You'd have to go on and on for quite a while before you could even get around to saying what the subject of the article is — and you'd have to repeat most of it for all the articles in category:large cardinals. That would significantly degrade the value of the articles for the readers who actually have a use for them. --Trovatore (talk) 23:55, 13 December 2021 (UTC)

Okay, thanks, I only glanced at it, see I didn't really take the time to understand it. Maybe you're right, maybe explaining the whole concept to average readers is too deep. But there are all kinds of ways to "explain" a technical concept for nontechnical people. I'm not suggesting replacing any of the technical definitions in the intro, just adding explanation for the majority of readers, who can't follow the other. Therefore it doesn't have to present the complete concept in all its complexity. A simplified explanation can be given, labeled as such. Analogy can be used. An example can be used, as I did above - I suspect that would work well for this article. Significance can be used: "The concept of measurable cardinal number is used in the field of ___ to prove the ____ theorem and in extending the ___ property to ___ mathematical structures". This is a general interest encyclopedia, and I think some effort should be made in the introduction to explain the topic to general readers. This article makes none. --Chetvorno^TALK 02:17, 14 December 2021 (UTC)

• "Everything should be made as simple as possible, but no simpler" -- attr. Einstein (though he didn't actually say it, at least not that way [12]) -- and bolding added, of course. EEng 00:18, 15 December 2021 (UTC)

In that quote Einstein was referring to scientists formulating the laws of physics, not explaining physics concepts to laypeople. --Chetvorno^TALK 02:32, 15 December 2021 (UTC)

This alert currently says "This section may be too technical for most readers to understand. Please help improve it to make it understandable to non-experts, without removing the technical details."

If a section is too technical, how can it be made understandable without removing the technical details?

That is a contradiction.

The problem is not a section that is too technical, but a section that fails to explain the technicalities in simple language. — Preceding unsigned comment added by Dratman (talk • contribs) 15:17, 3 July 2019 (UTC)

Unfortunately not all technicalities can be explained in simple language, at least not within the constraints of an encyclopedia article. Which I guess means that I agree with you to some extent; the template asks for the impossible, or at least some placements of the template ask for the impossible. --Trovatore (talk) 04:12, 20 July 2019 (UTC)

"Too technical" for most general purpose admins here means "more than zero equations". All math and physics articles should have this warning in bold red. Add "here be dragons" too. And a straw man picture. Joking aside, I wonder if this template ever made anyone help "improve" an article. I've seen templates more than 10 years old, and started removing them. How about we introduce "too historical" or "too trivial" templates? Why should one editor put such labels when readers can decide whether an article is too technical for themselves? Those who do find it "too technical" are free to improve it anyway. Ponor (talk) 02:25, 31 August 2020 (UTC)

I think there's a chance that the template helps occasionally, mostly by prompting some effort by an existing, active editor who is already working on the article. It's a bit like putting Template:Uncategorized on an article. We don't need it (because Special:UncategorizedPages exists), but the note sometimes prompts efforts by the person who is already working on it. WhatamIdoing (talk) 06:01, 3 September 2020 (UTC)

It's just one reader's opinion that becomes the first thing other readers see. A straw man. No trespassing sign. If it was meant for the existing editors of the article it would be on the article's talk page. Who exactly needs to be told that what they're going to read is "too technical"? What do readers do with that information? Leave? Read slowly? With only one eye open? Ponor (talk) 11:56, 3 September 2020 (UTC)

I'm not sure that readers pay attention to these tags. WhatamIdoing (talk) 00:32, 4 September 2020 (UTC)

I disagree with a good deal of the above:

• "It's just one reader's opinion..." There is a general opinion that WP technical articles are insufficiently understandable:

Wikipedia's science articles are elitist, 2017, Vice

Why are Wikipedia articles so difficult to understand?, Quora

You're not smart enough to read Wikipedia, Popkin, 2012, NBC

Maybe Wikipedia readers shouldn't need science degrees to digest articles about basic topics, 2017, SlashDot.

We should regard this template as a valuable heads-up to make our articles more useful for our readers.

• "...not all technicalities can be explained in simple language..." This rests on a misunderstanding of what "explaining" a subject consists of. Anyone who thinks there are subjects too advanced to explain in simple language should look at Hawking's A Brief History of Time. Explaining technical subjects to nontechnical people is simply a skill like any other. There is a huge industry devoted to this important task: there are many many general interest books explaining the most advanced scientific subjects, popular science magazines, cable channels like Discovery and National Geographic, TEDtalks, hundreds of Youtube videos explaining the most esoteric concepts, geek science websites, newsletters, industry training programs and white papers. That is the business we technical Wikipedia editors are in. But unless they are studying technical writing, most people in STEM fields don't get much training in this skill, because they don't need it; their communication is with others in their field. On Wikipedia we need it, and this lack shows in our articles.
• "I wonder if this template ever made anyone help "improve" an article." I've spent a large part of my 15 years as a WP editor improving technical articles so they are more understandable by general readers. I've probably worked on a hundred articles with that template. Typically you see one of 2 problems in our technical articles: either they are written by an amateur who is insufficiently knowledgeable, or they are written by an expert who for one reason or another doesn't write for general readers.

--Chetvorno^TALK 23:09, 14 December 2021 (UTC)

• So just responding to the one where you called me out directly, about whether technicalities can be explained in simple language. I think you and I have a fundamental disagreement about what it means to "explain" something. What you're talking about, I would call "popularizing" rather than "explaining". Popularizations give people the feeling that they understand something. But it's mostly an illusion.
  They know some vague generalities about the subject matter, and some of those may even be accurate, after a fashion. They can't do anything with it. They can't go from there to derive further accurate statements about the subject matter. They can't distinguish correct statements from ones made to sound like the ones they've already heard.
  I don't mean to suggest that popularization has no value. It can get people excited about a field. Sometimes, if they're at the right stage of life and have the right talents, it might even get them to go into the field, and advance it. And it can be useful to people interested in seriously exploring a field, to have a sort of a roadmap to hang concepts on.
  But that is not, in my view, the proper goal of an encyclopedia. An encyclopedia is a place to look stuff up, not a document to lead readers along a garden path. In particular

  lies to children have no place here whatsoever. --Trovatore (talk

  ) 06:16, 15 December 2021 (UTC)

Music

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

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

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

— Preceding unsigned comment added by TCO (talk • contribs) 17:25, 16 February 2011 (UTC)

Here are some opinions about the comprehensibility of our articles:

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

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

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

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

... but praises Simple Wikipedia's counterpart:

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

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

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

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

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

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

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

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

"Bessel functions, first defined by the mathematician

Friedrich Bessel, are canonical solutions y(x) of Bessel's differential equation

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

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

smooth functions

of ${\displaystyle \alpha }$.

The most important cases are when ${\displaystyle \alpha }$ is an integer or half-integer. Bessel functions for integer ${\displaystyle \alpha }$ are also known as cylinder functions or the

cylindrical coordinates. Spherical Bessel functions

with half-integer ${\displaystyle \alpha }$ are obtained when the

spherical coordinates

."

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

"A Bessel function, also called cylinder function, is any of a set of

mathematical functions

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

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

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

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

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

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