Jump to content

Wikipedia talk:Make technical articles understandable/Archive 2

Page contents not supported in other languages.
From Wikipedia, the free encyclopedia
Archive 1Archive 2Archive 3

Audit suggestion

Dear colleagues

I've had a preliminary look through this page. May I make two comments?

First, I think the opening point is slightly overstated. I refer in particular to this:

"Articles in Wikipedia should be accessible to the widest possible audience. For most articles, this means accessible to a general audience."

And this:

"Every reasonable attempt should be made to ensure that material is presented in the most widely accessible manner possible."

I think we have to accept that—like it or not—the project is now host to some highly technical articles that are pretty tough going for the non-expert. Some of these are even Featured Articles. Yet the basic premise of this MoS, which is mandatory for FAs to follow, is strident and uncompromising: these articles should be rewritten. This message almost undermines the valuable point made at the end of the lead, that "Introduction to X" articles are often a good solution. I note also that many WPians may be confused by the instruction not to "dumb down" an article to make it more accessible.

My second impression is that the main section, "Ideas for enhanced accessibility", has the tone and content of an essay rather than a styleguide. Some of it is damn good advice, but is hard to frame in ways that involve personal style, or that closely depend on context. I'm referring to such points as "Add a picture", "Explain forumalae in English", and "Put the most accessible parts of the article up front". This is good general advice, but I'd like to suggest that it is inappropriate as part of the Manual of Style, in which more cut-and-dried guidance and rules are the norm.

The WP Styleguide Taskforce aims to rationalise the unwieldy mass of pages that have grown in the MoS over the years. I would like to suggest that this page be turned into an essay, and that its main messages be raised to greater prominence in just a few sentences in the main MoS page, with a link to the essay.

Please let us know what you think of this suggestion. We are also auditing Wikipedia:Technical terms and definitions and Wikipedia:Explain jargon. Tony (talk) 10:34, 1 April 2010 (UTC)

PS, I'm very wobbly about these two points, even if this is retained as an essay:

  • Use short sentences when possible. Comprehension decreases dramatically when sentence length exceeds 12 words. However, using too many short sentences in a row becomes monotonous; vary sentence length to maintain reader interest.
  • Use more verbs to improve readability — you can replace many technical adjectives with verbs. Tony (talk) 13:01, 1 April 2010 (UTC)
    These have been principles of web writing since the late 1990s, see a few sources at User:Philcha#Writing_style. --Philcha (talk) 06:15, 4 April 2010 (UTC)

RFC: Should this guideline exist, or should it be an essay?

This page was summarily removed without sufficient discussion. As this has been part of MOS for years, it should at least be discussed. --Rschen7754 08:53, 2 April 2010 (UTC)

Rather than reverting without stated reason, perhaps you would like to start by addressing the issues raised above. Tony (talk) 09:22, 2 April 2010 (UTC)
  • I think opening a Rfc is overkill. You could just have added your opinion to the previous section. But I completely agree with you that with turning this into an essay User:Tony1 was taking too much responsibility on his shoulders without first seeking consensus. Debresser (talk) 09:27, 2 April 2010 (UTC)
  • Essay for now with aim to make Guideline. I agree with both side as it stand this is written as an essay and need some but not major work to come up to MOS which it should be part of Gnevin (talk) 09:52, 2 April 2010 (UTC)
  • Essay - given its terminology, and its exploring of possibilities rather than straight presentation of "this is the house style". (On a side note, I think the use of the word "accessible" is problematic for a web-based resource, since in that context it's strongly associated with with Web accessibility, which isn't the focus here.) PL290 (talk) 11:20, 3 April 2010 (UTC)
Hi, PL290, web accessiblity is just a subset of software accessiblity. A designer of buildings or vehicles would have a different perspective on easy of use for people with difficulties more the "norm". And both are metaphors based on the difficulties of some locations / routes. In short, web / software accessiblity tail should not be allowed to wag the whole dog. --Philcha (talk) 11:54, 3 April 2010 (UTC)
I realize that, and I agree with that principle, but my point is (and I see I didn't say it clearly), Accessibility (web or other) is now strongly associated with ensuring people with disabilities are able to use a facility of any kind. Since that is not the focus here, another term (comprehensible; understandable; clear to the target audience ...) might be, er, clearer to the target audience. PL290 (talk) 12:34, 3 April 2010 (UTC)
Still no comments on my points above ... overkill at the opening; the points that have no real basis in terms of sources/research (12 words? why not 11 or 13? what about the context?). Tony (talk) 14:00, 3 April 2010 (UTC)
Tony this discussion is if this should be a guideline or essay not about the issues you've raised. I'd suggest a move to WP:Make_technical_articles understandable Gnevin (talk) 17:02, 3 April 2010 (UTC)
It is no service to editors that the MoS be a sprawling mess of overlap and repetition. That is why I added this subsection to the central MoS page a few days ago, expecting that here people would concentrate on the big picture of serving the project as well as possible. What I'm seeing is a local attempt to retain an unnecessary and somewhat problematic separate page. Instead, we need to remove the unnecessary, cut to the chase and express the core meaning as now at the MoS. Can anyone tell me what is missing from the subsection I inserted? If not, this page should no longer be part of the MoS subpages, where it is increasingly difficult for editors to keep track of it and ensure consistency of message. Tony (talk) 00:38, 4 April 2010 (UTC)
Actually a very necessary guideline, if we may judge by the number of times the {{Technical}} template is used. Note that its documentation referes to this guideline. What I am seeing is a one-man war against a Wikipedia guideline... So let's leave the polemics aside and just see what this Rfc leads to. Debresser (talk) 06:07, 4 April 2010 (UTC)
Whats missing well for one your paragraph doesn't give suggestions as how to make articles more understandable .Doens't advise how to deal with the unavoidabley complex such as maths or advise about Introduction to articles. Thats at a first glance Gnevin (talk) 12:43, 4 April 2010 (UTC)
To clarify my earlier response:
  1. A summary style mention in the main MoS is definitely needed, if there wasn't one there already.
  2. I specifically meant, all 3 articles should be merged to a single location. ("Merging" meaning taking the details that are truely needed; not just a copy&paste dump-merge; nor just redirecting without doing any content-preservation, as may have occurred at Wikipedia:Explain jargon)
  3. I think a lot of the single bullet points in all 3 pages will have a lot of discussion behind them. They should probably be preserved somewhere, even if its just at an historic page.
  4. Some parts are definitely best left out (and some will need discussion first), but I completely agree with your first two comments here. On the other hand, some of the information, eg at Wikipedia:Technical terms and definitions, could probably be "merged" to (or considered as being already "covered" by) pages such as Wikipedia:Manual of Style (text formatting) and Wikipedia:Words to avoid and Wikipedia:Writing better articles
  5. So, essentially, I hope any merge effort results in not just reducing the overall quantity of pages, but also in dispersing the information that was in those pages to the remaining, more appropriate, subpages. HTH. -- Quiddity (talk) 07:14, 4 April 2010 (UTC)
Fine, but there's a lot wrong with this page, and we certainly don't want three or even two fragments: that is not a service to editors. You have your mention of the message in MoS mainpage now. What more? Tony (talk) 11:36, 4 April 2010 (UTC)
  • Guideline, though not a "style guideline", as it doesn't address "style" in the narrow sense of formatting. There are too many people wrongly believing that comprehensibility and factual accuracy are incompatible, and forsake either (or both) goals. ― ___A._di_M. (formerly Army1987) 13:41, 4 April 2010 (UTC)
  • My answer is difficult to sum up in one word :) - a) the present page is not exclusively designed to address MoS issues; b) anything that does give specific MoS advice could easily be summarised either in in the main MoS or a dedicated topic-specific MoS (see later); c) we do need advice such as that presented on the page, e.g. the general advice to consider the average reader when discussing technical subjects and why (and when) usage of technical terminology and language should be avoided while avoiding "dumbing down"; d) the page would be better as an essay as a counterpart to the recently moved and merged (?) Wikipedia:Technical terms and definitions unless that too should be merged into the main MoS. Therefore, "Essay for now pending further discussion" seems to be the best approach --Jubilee♫clipman 20:16, 4 April 2010 (UTC)

Post RfC comments

  • The problem with this page is that it's too vague to be a guideline. For instance "Every reasonable attempt should be made to ensure that material is presented in the most widely understandable manner possible." Some interpret this above as making everything accessible to 14-year olds. Others, interpret it as making the stuff accessible only to those that have a working knowledge of the prerequisites, i.e. depending on the difficulty of the topic. There's a very related discussion at Wikipedia talk:Scientific citation guidelines#Snake lemma as example. Looking over this page, I don't see much in the way of practical advice that could help there. Tijfo098 (talk) 05:54, 28 November 2010 (UTC)

Use language similar to what you would use in a conversation

I am not sure what "Use language similar to what you would use in a conversation" is supposed to mean, but it seems misworded to me. The language I would use in a conversation is going to be full of contractions and sentence fragments; it is not likely to be in the encyclopedic tone that we strive for here. — Carl (CBM · talk) 13:03, 7 April 2010 (UTC)

Yes, it is completely misleading. Oral and written modes are two different languages; two different grammars. Sentences are nefarious in free speech, for example. I think this whole page needs to be rethought, for fear of misleading editors. Tony (talk) 13:21, 7 April 2010 (UTC)
Also, physicists (for example) talking with other physicists about physics (TBBT is more realistic than one might think) will often use words incomprehensible to outsiders even in oral conversations, so that doesn't even solve the problem... I think I understand what the point of that is supposed to be (in Italy we say "speak the way you eat"), but I can't find a better way to state it right now (though I might when I'm fully awake). ― ___A._di_M. (formerly Army1987) 13:45, 7 April 2010 (UTC)
What ADM says draws us to a critical point: the page—if it is to remain in some form—needs to define in greater detail the circumstances in which an article might be less than accessible to the 14 year old. Where does one draw the line, and in relation to which topics or areas? I can't imagine why it is an imperative that an article on twisted quantum algebra should be held to the current opening announcement that "Articles in Wikipedia should be understandable to the widest possible audience. For most articles, this means understandable to a general audience.... Every reasonable attempt should be made to ensure that material is presented in the most widely understandable manner possible. If an article is written in a highly technical manner, but the material permits a more understandable explanation, then editors are strongly encouraged to rewrite it."
It all seems to be a bit hard-line that such a general statement should be part of a styleguide in such a wide-ranging resource as WP. We could certainly take quite a number of FAs to the cleaners on this basis: have them demoted. Are nominators and reviewers at FAC aware of their obligation to follow this guideline, since it is part of the MoS? Taken at its word, this page really does force a dumbing down of some of WP's more technical areas. Why? Doesn't WP have a role as an information resource for specialists, too? Tony (talk) 14:06, 7 April 2010 (UTC)
I don't read it that way: the "most articles" and "reasonable attempt" (emphasis added) parts make the intent clear (at least to me). It also doesn't forbid having both a general, widely comprehensible picture first and technical details later in the same article, which is typically the best thing to do. (Can you point examples of FAs which don't follow this guideline?) ― ___A._di_M. (formerly Army1987) 15:30, 7 April 2010 (UTC)
We certainly have a role for specialists and specialized articles. I frequently see professional mathematicians look up things in wikipedia (in front of me) or cite wikipedia for general things in emails and conference talks. Of course they don't cite it in papers, for obvious reasons, but it is nevertheless an important resource. However, the proportion of technical articles to overall articles is extremely low. The math project only has about 23,000 articles out of 3,000,000, and that includes all the articles on basic topics. So I have always read "widest possible audience" to mean "widest possible audience given the level at which the material is usually studied". Also, I like to point out that the problem is not limited to mathematics. How many 14-year-olds will actually understand the first paragraph of B-flat minor? I don't understand it without chasing links, but I believe it's written at the right level for an encyclopedia. — Carl (CBM · talk) 16:56, 7 April 2010 (UTC)
Well, I certainly wouldn't take "Use language similar to what you would use in a conversation" so literally as to mean to write in sentence fragments and other features of spoken language (like "uh" or starting a sentence only to stop and revise it halfway through). I guess it makes most sense to me if directed at a writer who is having trouble loosening up, in a spirit like "if your text ends up too ponderous, try this" rather than as a rule which is specific enough to follow mechanically (like "use one space, not two, after a period at the end of sentence"). The page which is linked at that point has a lot of stuff but what struck me most was the example from [1] of saying "Let's cache the data in the listener" rather than "we should optimize receipt by instantiating an automated redundant store of information made available to the packet receipient module". Perhaps this helps give some feel for how we should write about technical subjects, including all necessary technical detail, but not that which serves merely to erect a barrier to comprehension. Kingdon (talk) 02:34, 9 April 2010 (UTC)
"Let's cache the data in the listener" may be as bad - with my age and background I find "we should optimize receipt by instantiating an automated redundant store of information made available to the packet receipient module" easier :-) Perhaps "to make conversations quicker, data that is often used should be stored at the receiving end". -Philcha (talk) 10:10, 10 April 2010 (UTC)
What about "Do no write complicated stuff just because it's fancier; that's something which lawyers do in contracts etc. because they want you not to understand them; but you don't what that in WP articles." (Not with this exact wording, of course.) ― ___A._di_M. (formerly Army1987) 18:41, 11 April 2010 (UTC)
I think it's better for us to simply follow the language patterns used in the literature (introductory and specialized) about a particular topic. — Carl (CBM · talk) 23:19, 11 April 2010 (UTC)
A.K.A. "plagiarism"? ― ___A._di_M. (formerly Army1987) 11:47, 14 April 2010 (UTC)
You have misread what I wrote. — Carl (CBM · talk) 13:35, 14 April 2010 (UTC)
Ah, if by "language patterns" you just meant that articles should be written using Standard English syntax, I agree, but what does this have to do with technicalness? ― ___A._di_M. (formerly Army1987) 16:16, 14 April 2010 (UTC)
I think that it's generally best for our articles to resemble the sources they use in terms of tone and technicality. Different articles, such as Apple, B-flat minor, and Grothendieck universe, will unavoidably be different in their use of technical terminology. — Carl (CBM · talk) 18:04, 14 April 2010 (UTC)

But this is an encyclopaedia, and not all of the sources are. There's a widely used university textbook on quantum mechanics written by a physics professor and published by a major publisher, and used as a source on several WP articles, which includes the sentence:

I drew the figure so as to make you think of a car approaching a cliff, but obviously the probability of "bouncing back" from the edge of a cliff is far smaller than what you got in (a)—unless you're Bugs Bunny.

You wouldn't say anything like that in a WP article, would you? I think the converse issue – using legalese-sounding technical language when "plain English" would be no less precise, just because a source does the same for the sake of it – wouldn't be any less bad. See also WP:NOT PAPERS (part of a policy), especially points 4, 5 and 7. ― ___A._di_M. (formerly Army1987) 13:55, 15 April 2010 (UTC)

No, I would not want us to write like that particular book. Point 7 of WP:NOT has to be read correctly. Part 7 is appropriate when there is a common term and a scientific term for the same concept (for example, we would usually talk about the "speed" of a car, not its "instantaneous velocity"). But there is no other word for "topology", for example, that we could use in articles that discuss that concept. That is, for certain topics like Grothendieck universe, the common language for the topic is the academic language, because this is the only language in which the topic is ever discussed. However, such articles are a tiny fraction of the overall content. — Carl (CBM · talk) 14:57, 15 April 2010 (UTC)
Actually, the speed and the velocity aren't the same: one is a scalar and one is a vector. But you don't usually need to refer to the latter when not doing physics. And in most context both the speed and the velocity are assumed to be instantaneous unless otherwise specified, whether in physics or anywhere else. But I get the point. ― ___A._di_M. (formerly Army1987) 15:15, 15 April 2010 (UTC)

Intention to tag this as an essay

Nothing has happened, despite the inclusion in the main MoS page of what to me looks like a useful, succinct encapsulation of what this page is conveying.

Unless someone can identify what is missing from that section that is worth retaining from this page, I intend to withdraw this page from the list of MoS pages and leave it as an essay prominently linked to from that main MoS section. Tony (talk) 02:41, 13 April 2010 (UTC)

In view of the fact that there is a Rfc on this talkpage, addressing just this question, this section is moot. Tony1, how did you get on that MoS assessment board? Don't you know how things work on Wikipedia. Debresser (talk) 04:06, 14 April 2010 (UTC)
I think this should still be a guideline. I'm think the list of techniques here would take too space on the main MOS page; and the Main page should emphasise easy of reading (general, not technical) and link to "Make (technical) articles understandable". --Philcha (talk) 06:23, 14 April 2010 (UTC)
The main page does now do this, since I added a subsection two weeks ago; but that was part of the scheme to remove this page from the MoS category, since we have a huge plethora of MoSes, and want to rationalise it. This page, I put it to you, still reads like an essay: it is full of opinion. Tony (talk) 13:38, 14 April 2010 (UTC)
This is not "full of opinion", just not full of MOS's opinion. But MOS ignores the opinions of experts on editing for the web, e.g. Web Style Guide: Online Style or Writing for Readers Who Scan. --Philcha (talk) 14:12, 14 April 2010 (UTC)

?Introductory articles?

Opinion: I personally disagree with the whole notion of "introductory articles". I think the very idea runs contrary to the idea of Wikipedia. Wikipedia is specifically intended to be accessible by everyone. If one is contemplating creating a dumbed down version of an article on some topic, one should ask a simple question: "If it is possible to make this topic easier to understand, why am I not doing that to the original article instead of forking to a new article?" The technically minded author may argue that to fully discuss the topic, one must be too technical for the comprehension of the novice reader. This is a lazy excuse. Usually the real motivation is technical experts want to write articles that impress their peers rather than articles that are easy to understand. Wikipedia is not the place for such displays of vanity.

Proposal: Eliminate the suggestion for creating "introductory articles" in this essay. Instead include something like the following:

Avoid introductory articles
Many topics are unavoidably technical when treating them in detail. It is often tempting to create a detailed technical article on the subject for the experts and a more simple introductory article for the less technically oriented readers. One of two things, though, must be true: either the topic is so technical that a non-technical article is not possible, or the non-technical introduction could be put into the technical article. The advantage of the latter is that the reader can go as deep into the technical details as he/she cares to. The idea that all readers can be neatly divided into "technical" and "non-technical" is elitist and generally does not reflect reality.
It may be the case that including all of the less technical introductory material and the detailed technical details makes the article too long. This, however, is not a reason to create a redundant introductory article. Rather it is a better idea to identify specific subtopics in the article that can be split out into their own articles. Such an approach makes articles flow better, avoids content forks, and doesn't insult anybody's intelligence.

--Mcorazao (talk) 05:01, 4 June 2010 (UTC)

I think you need to recognise that articles differ. A lot of my work is on zoology, and so far I think I've used non-technical phrasing. Maths is more variable, and often necessary technical. I saw one in the last couple months where non-technical phrasing seem to have done the job. OTOH recent, advanced techniques are needed to prove Fermat's last theorem, an mathematician would expect to read this all this, a non-technical version would be needed for non-mathematicians, and a mathematician should check the non-mathematical version to make it has no errors. --Philcha (talk) 09:05, 4 June 2010 (UTC)
Respectfully, I do not agree. Whether or not advanced techniques are necessary to prove Fermat's last theorem is irrelevant. There is no rule that says any particular reader must be able to read the entire article. It is in fact, perfectly reasonable, even advantageous, to have an article start with a very high-level, simple explanation and gradually delve into more of the details. The reader can decide at what point he/she has gotten what they want out of it. Deliberately creating articles that are intended to exclude some readers is not what Wikipedia is designed to do (and I don't think that is a road we should be going down).
So you have not demonstrated (to my understanding) any reason to fork Fermat's last theorem. Can you name a topic that could not be usefully described by first starting with a simplified description and then gradually delving into the details (excepting, of course, topics where it is impossible to create any article that a novice could ever understand)?
--Mcorazao (talk) 14:09, 4 June 2010 (UTC)
P.S. Refer to WP:NOTTEXTBOOK. It says

A Wikipedia article should not be presented on the assumption that the reader is well versed in the topic's field. Introductory language in the lead and initial sections of the article should be written in plain terms and concepts that can be understood by any literate reader of Wikipedia without any knowledge in the given field before advancing to more detailed explanations of the topic.

In other words, an article should be written to be accessible by everyone, at least in the introductory material. And articles should stand on their own. It should not be necessary to redirect readers to other articles because the article in question is incomprehensible. Or to put it a different way, the very fact that you are creating an introductory article implies that you are violating WP:NOTTEXTBOOK on the original article. --Mcorazao (talk) 16:06, 4 June 2010 (UTC)
Can you point to some examples of articles which are written in this style, combining both highly technical and much less technical material in the same article (beyond just lead versus non-lead)? I'm sure there are some, because there are plenty of cases where noone wants an introduction article. This page would benefit from more examples in general (of real articles, preferably good and/or featured). We already say "the number of separate introductory articles should be kept to a minimum" and if we want to strengthen that I'd want to see more about how the situations would be handled which currently have introduction articles. Kingdon (talk) 01:39, 6 June 2010 (UTC)
Not sure what you are asking. Do you mean examples of articles that are well-written in terms being accessible and still being very technical? A couple of FA articles that probably qualify are star and Europa (moon). These articles contain very technical information, including information that would tend to make the average reader's eyes cross. Yet they are generally very accessible in terms of presenting the early information in a non-jargon-rich way and postponing the most complex details for later in the article.
--Mcorazao (talk) 06:18, 8 June 2010 (UTC)
Yes, thanks, that's the kind of example I was looking for. I've taken the liberty of adding those to the page. I agree that these articles represent the kind of work we should be encouraging and do a good job of handling technical material. Kingdon (talk) 03:37, 15 June 2010 (UTC)

Avoid the angry drumbeat of technical terms

In many article on what would be interesting topics (particulary biology) there is a tendancy for people to use technical terms, OFTEN completely synonymous (or synonymous to the extent there is NO danger of confusion on the term) with a common English word. I have heard it said, the wikilink takes care of it. But we should consider the guidance that people will not follow the link. Also that "it might be nice for people to learn a new word" should be used in extreme moderation. If someone is learning new material, also learning new words is painful. And this is not a textbook. It's an encyclopedia. There should be a little bit of reading joy in the articles, rather than an attitude of teaching people Subject101 as it would in a textbook. And it's not an issue of a single new word (as perhaps you might have in an article on a historical subject) but of a bristling array of new terms and of them repeating down the page like an angry drumbeat. TCO (talk) 15:28, 18 December 2010 (UTC)

Guideline status restored

I've restored the guideline status. Recent discussions at WT:FAC found that while we disagreed over the degree of edtiorial restraint that editors felt should exercise wrt advanced technical material, there was support for the principle that we should be making every effort to reach the widest audience. Several editors felt the guideline was wrongly demoted to an essay. The nutshell was taken from that discussion. Colin°Talk 10:30, 15 February 2011 (UTC)

There was an RFC (above), which does not show consensus to demote a long-standing guideline (which reflects WP:NOT policy) to an essay; I agree with the restoral, as the demotion was incorrect. SandyGeorgia (Talk) 12:27, 15 February 2011 (UTC)
One difficulty is that WP:NOT points can be in conflict. In particular, from WP:NOT, "Wikipedia is an encyclopedic reference, not a textbook. The purpose of Wikipedia is to present facts, not to teach subject matter." Efforts to make articles more accessible will often run into this policy, and into the NOR policy. I have left some more detailed comments below. — Carl (CBM · talk) 12:44, 15 February 2011 (UTC)
I have also removed a very strange hatnote from this talk page; since when does one person "audit" community guideline pages? SandyGeorgia (Talk) 13:02, 15 February 2011 (UTC)
I support the decision to restore its official status as a guideline. WhatamIdoing (talk) 05:10, 16 February 2011 (UTC)

Comments by CBM 2011-2-15

There is certainly agreement that every article should reach the widest possible audience for that article. In particular, the lede section of an article should go out of its way to establish the topic and its context in a way that is as accessible as possible. I have previously suggested elsewhere that the lede of a technical article should answer three questions:

  1. What is it? Is the reader at the article they want? What is the article going to be about? A formal definition isn't necessary if it is provided in the body of the article.
  2. Who studies it? What is the context of the topic? Where can the reader go to find background material?
  3. Why is it studied? Why is it interesting? Why would the reader want to read about it?

I think that, as a minimum, the lede of a technical article should make the answers to these clear. For many readers, just knowing the answers to these questions may be enough to satisfy them.

However, this guideline accepts that articles on technical topics are not going to be accessible to a completely general audience. In particular, the article that was discussed at WT:FAC (Rhodocene) is of the exceptional type that has some unavoidably technical content. However, I think that the lede does answer my three questions. Just having a few long words does not make an article "technical"; readers need to be willing to read, rather than skim, and to skip words they are unfamiliar with the get the general meaning. If you do that, the lede of that article does explain the topic, context, and interest just fine. The article is an FA, so that's not too surprising.

For the most part, this guideline reasonably allows for article like rhodocene to be more technical, and so the guideline fits in with current practice. For that reason, I don't oppose it being marked as a guideline.

My main criticism of this guildeine is that many of its suggestions are in (mild) conflict with other policies. For example, the idea that we should explain formulas can conflict with NOR and the "not a textbook" policy. The idea of adding examples is good, but many examples are original research, and having too many examples again violates NOT:TEXTBOOK.

These conflicts leave editors with a choice. We could write a perfectly nice set of lecture notes on a topic, with clear prose and examples. But it would be in complete violation of the NOR policy, and arguably would be too much like a textbook. Or we could write a well-sourced reference article that simply summarizes the content of reliable sources, but that will be more technical. Given the choice, I generally go with following the NOR policy at a cost of keeping the article more technical.

Finally, I want to point out that if there is concern about technical articles at FA, that's a matter for the FA people to decide for themselves. FA is an independent group, essentially just a differently named WikiProject, and editors can choose whether to participate in FA or not. The FA requirements should not be confused with Wikipedia-wide guidelines, any more than any other WikiProject's internal goals would be. — Carl (CBM · talk) 12:43, 15 February 2011 (UTC)

By all means, improve this page (it needs it), but the very problem with rhodocene is that it does not answer those questions in the lead in a manner accessible to general readers, as explained by one reviewer on the FAC. Further, this guideline is not about FAs or FACs; it reflects [[WP:NOT}] policy and WP:LEAD guideline. Please don't conflate the issue with one FAC. FA is "not an independent group": FAs reflect Wiki's best work, and must conform to policy. SandyGeorgia (Talk) 12:48, 15 February 2011 (UTC)
Sure; Colin justified the change (above) with "Recent discussions at FAC", so I wanted to respond to that. — Carl (CBM · talk) 12:50, 15 February 2011 (UTC)
For rhodocene, here are the answers to my questions, from its lede:
  1. What is it? A chemical. Answered in detail in the first paragraph.
  2. Who studies it? Organometallic chemists and biomedical researchers (paras. 2 and 4)
  3. Why is it important? Middle of para. 2: it has interesting chemical properties. Paras. 4 and 5: applications to research
Like I said, it is necessary to actually read the article in detail. If "general readers" means "people who don't actually read the text" then I think we should not worry about those people too much: nothing will help people who don't actually read the article. — Carl (CBM · talk) 12:54, 15 February 2011 (UTC)
I notice that your answers make allegations that aren't supported by actual words; since you believe the article answers those questions, perhaps you will be able to make the text in the lead comprehensible to those of us who don't see the answers to those questions (reference Kleopatra's comments on the FAC, which were apparently never acted upon). It is necessary for all readers to be able to digest the lead: for starters, the lead is too long and dives immediately into extraneous technical detail, without clearly answering those questions for all readers. It would be wonderful if someone would work on that. SandyGeorgia (Talk) 13:05, 15 February 2011 (UTC)
I find that the text is comprehensible, that's where we disagree. The lede is supposed to summarize the article as well, so some technical detail is appropriate. Given that the article just passed FA, someone else must have been able to read it. Here are the words I see to answer the questions:
  1. "Rhodocene, formally known as bis(η5-cyclopentadienyl)rhodium(II), is a chemical compound" "It is considered an organometallic compound" "Rhodocene is described as having a sandwich molecular structure and it is an example of a metallocene, "
  2. "Organometallic chemistry first came to prominence" "Biomedical researchers have examined the applications of rhodium compounds in medicine"
  3. "Organometallic species such as these were of great interest because bonding models of the time were unable to explain their formation, let alone their stability." "Work on sandwich compounds, including the rhodocenium / rhodocene system, earned Geoffrey Wilkinson and Ernst Otto Fischer the 1973 Nobel Prize for Chemistry." "Biomedical researchers have examined the applications of rhodium compounds in medicine" "A more recent use of rhodocene derivatives has been the synthesis of linked metallocenes,[21] such as termetallocenes,[22] which are interesting for the insights they provide into metal–metal interactions"
If someone missed all those, it's hard to believe they actually read all the words in the lede of the article. — Carl (CBM · talk) 13:13, 15 February 2011 (UTC)
  1. Why "is considered"? Why "described"? Why do we need to know in the lead that it has a sandwich molecular structure and delve into metallocene? For starters.
  2. Which are?
  3. none of that tells the general reader anything. SandyGeorgia (Talk) 13:17, 15 February 2011 (UTC)
Consider that the lead may be so indigestible that few will want to read it. More importantly, since these concerns were raised in the FAC (and have been subsequently raised by others), why have they still not been acted upon? SandyGeorgia (Talk) 13:20, 15 February 2011 (UTC)
Please don't split my comments, just reply below them. It's a personal pet peeve.
  • For #1, "is considered" could mean "is" or it could foreshadow some difficulty in the classification. Knowing that rhodocene is a metalocene gives context: this is an example of a more general type of thing. You don't have to know what a metalocene is (I don't) to understand that.
  • For #2, the 4th paragraph goes on into more detail. But I thought you were complaining there was too much detail?
  • For #3, I have no idea what you mean. All of those sentences are perfectly clear. Winning the Nobel prize for studying something is a sign that something is important, I think.
Perhaps the reason that the concerns weren't "acted upon" is that (1) the article passed FAC and (2) other people disagree with the claimed difficulty reading the lede.
I'm being honest here - I can read the lede. It is not particularly dense. The sentences are short, and the terminology builds up over time so that I have seen certain words before even if I don't know their meaning (e.g. ferrocene). There's nothing objectively wrong with the writing. I am not a chemist, I don't understand the topic in depth, but I can read the lede just fine. That makes it hard for me to understand criticism like "none of that tells the general reader anything". — Carl (CBM · talk) 13:26, 15 February 2011 (UTC)

(←) Some of the comments make me think some reviewers may be falling into the trap of "fighting the text". For example, when I read "Organometallic species such as these were of great interest because bonding models of the time were unable to explain their formation, let alone their stability." I think these things in this order:

  • There is such a thing as a bonding model.
  • But the models could not explain how these chemicals form.
  • Also there is something called "stability" which must be of interest to chemists.
  • And the models couldn't explain that either.

So by reading that sentence, I learn various things (I'm not a chemist, I have no idea what a bonding model is, but now I know they exist).

The point is that you have to read the sentence on its own terms. If the authors want to explain who is interested, or what a bonding model is, they may do that in the body of the article. But in the lede, I have to take on faith that there is such a thing as a bonding model, and go from there. When I'm reading, I can't "fight" the text by constantly wishing that it answered different questions than I did, or went in a different order. I have to take the text and read it as it stands, in entirety, before trying to analyze it. When I do read this text on its own terms, I find that it conveys a significant amount of information.

Put another way: people like me who edit prose on a routine basis need to put that out of our heads when reading other people's prose. The question "what does this say" is different than the question "How would I have written this". For topics you aren't familiar with, you have to step out the "editor" role and into the "reader" role, where you accept that it is already written and your goal is to read it to see what it says. — Carl (CBM · talk) 13:42, 15 February 2011 (UTC)

I don't see the point in continuing to discuss this particular article on this guideline page; concerns were rasied on the FAC and on article talk, and at WT:FAC. Someone needs to fix the article, and EdChem doesn't seem willing or able. But this page is for discussion of the guideline, specifically, why it was demoted by one editor. SandyGeorgia (Talk) 13:52, 15 February 2011 (UTC)
If you look at my original comments, they were all about this guideline, not about whether FA reviewers could read the lede of rhodocene. — Carl (CBM · talk) 13:57, 15 February 2011 (UTC)
All readers should be able to read the lead; if FA reviewers can't, certainly general readers will have a problem. If you aren't able to help out on this article, perhaps we can locate someone who can? SandyGeorgia (Talk) 13:58, 15 February 2011 (UTC)
I think that FA reviewers are perfectly able to read the lede; they are by and large a pretty literate group. So I am skeptical of any claims to the contrary. The lede has a reading level no higher than typical undergrad textbooks or excerpts you would see on the GRE, and people read those perfectly well. And the article passed FA for goodness' sake! So claims that the article is in dire straights are exaggerated.
But can't we stick to the topic of this guideline, like you proposed? I would also prefer that. If you want to discuss the article let's do that on its talk page. — Carl (CBM · talk) 14:06, 15 February 2011 (UTC)
Passed FA in this case means that three editors supported it, and it happens that all of them where editors familiar with the topic area, and one of them was also the GA reviewer (involved)-- consensus changes, and three editors won't be able to defend it if it hits the mainpage. More importantly, the concerns about the lead and the prose were raised on the FAC, and many other places. I'll hope others will address it before it ends up at FAR, and focus on working on this guideline. I did some preliminary work here, but more is needed. I see two separate problems that led to this: 1) declining participation across Wikipedia in all content review processes (the days of dozens of FAC supports indicating a broad level of review and support are behind us), and 2) unilaterial demotion of a long-standing guideline that reflects policy, so that a few MOS editors are dictating content on the mainpage. One of the (many) reasons that leads are important in FAs is that, from the lead the TFA blurb is crafted. I don't see any way to craft a blurb from this article's lead that will benefit the general readers of Wikipedia's main page. I hope someone will fix that. SandyGeorgia (Talk) 14:24, 15 February 2011 (UTC)
I have an advanced degree in chemistry, and while I understand the lead of rhodocene, I don't understand the lead of rhodocene. Saying that it hit those three points (what it is, who studies it, why is it important) are hit, and pointing to how it is mish-mashed through 3 different paragraphs, is basically going through the motions but not stepping back to make sure everything makes sense. Once you are past the lead, its difficult to say how the rest of the article should be approached, but no one should be confused by the lead even if buried in it the core questions are answered.
This guideline needs to be written like WP:WAF but for technical topics. People dealing with fiction - where it is possible to get buried in details of a show's complex plot just as tech articles can be - seem to deal with this fine, so there's no reason technical articles can't be improved as well. --MASEM (t) 14:49, 15 February 2011 (UTC)

I like Carl's three questions. However, I'm not sure that #2 ("Who studies it?") is quite the right way to put it for any article that isn't primarily or strictly academic in nature. What matters about, say, lasers or cancer, is not exactly "who studies it". (I unfortunately do not have a better suggestion for communicating the point behind this item, which is clear to me.) WhatamIdoing (talk) 05:13, 16 February 2011 (UTC)

Examples

Rather than beating rhodocene more, let's look at a couple different examples: Diagonal lemma (a short article) and Aldol reaction (a featured article). What do you think about the ledes of those articles? Feel free to suggest your own examples for people to comment on. — Carl (CBM · talk) 15:15, 15 February 2011 (UTC)

Diagonal lemma has little to establish what it is to a layperson, so that's not a good case. The Aldol reaction gets too detailed too fast - its almost if the 2nd and 3rd para should be switched to get the why addressed before the what, but that's not the only thing that can be improved. --MASEM (t) 15:19, 15 February 2011 (UTC)
Aldol reaction was promoted in 2006 and has many obvious problems: it needs to a visit to Wp:FAR (it doesn't look like anyone is maintaining it, and it should not be an FA in its current state). Diagonal lemma does, too, but it's not an FA, and is what I would expect from its class of article. SandyGeorgia (Talk) 15:29, 15 February 2011 (UTC)
@Masem: I don't follow the comment about diagonal lemma. We have lots of B-class (or lower) technical articles, which this guideline would also give advice on. The lede of that article is short, but I think it answers the three questions.
What I'd like to find are some examples of articles on unquestionably technical topics (e.g. studied at the graduate level) for which the lede unquestionably meets the accessibility goals of this guideline. Then we could use those as models and to help focus the discussion. Do you know of any examples at all? I am looking for some and will report back. — Carl (CBM · talk) 15:34, 15 February 2011 (UTC)
I think the biology editors generally do a good job-- even if I don't follow everything they're saying, I can deduce from the context the gist of what they're discussing, and can tell that if I wanted to know more, I could click on links. The point is, when I read them, I'm not lost, but I know how to find more detail if I want it. Math and physics, are IMO, are among our worst offenders. SandyGeorgia (Talk) 15:40, 15 February 2011 (UTC)
Usually, the ability to deduce what's going on is based more on background knowledge. For example, an editor with an interest in medicine might find biology easier just because of shared prerequisite material or a familiar writing style. "Offenders" is pretty strong language given that accessibility to 8th graders is only one of several competing goals, and for graduate-level topics there has never been agreement the appropriate level of accessibility. — Carl (CBM · talk) 15:58, 15 February 2011 (UTC)
Yes, well, while I have no medical background, I was a physics undergrad, switched to math, statistics/engineering/computing (OR) grad, HATE biology-- so I do expect to find math and physics articles more (personally) digestible than medical articles. What I find instead is that most reviewers gloss over them because they mistakenly think the crappy prose is just highly technical material. In fact, I might specifically add that one reason so many of our medical articles are in good shape is because several of the "regulars" are laypersons, and we try to make sure they're digestible, while there are, AFAIK, very few non-math editors working on those articles, as an example. SandyGeorgia (Talk) 16:08, 15 February 2011 (UTC)
On diagonal lemma, here is the lead: In mathematical logic, the diagonal lemma or fixed point theorem establishes the existence of self-referential sentences in formal theories of the natural numbers, if those theories are strong enough to represent all computable functions. Such sentences can be used to prove fundamental results such as Gödel's incompleteness theorems and Tarski's indefinability theorem.. I know some modern algebra and I've read through GEB so I understand the words but not anything about what this is at all from that. there's no sense of what this concept is to the layperson. What is it used for practically? Is it an aspect of natural language processing and artificial intelligence studies (as I'm trying to infer from the rest of the article)? This is a problem. Looking at the article, I would agree that 90% of it is going to be over the average reader's head, but lets get that first 10% in a manner that meets the comprehension for everyone. --MASEM (t) 16:36, 15 February 2011 (UTC)


Continuing my search for examples, Poincaré conjecture seems to have a pretty acessible lede; it was in the news a while back, so people probably worked on accessibility at that time. I also looked at Hydrochloric acid and Acetic acid, both featured articles. Those are not particularly advanced topics, so they're not really examples, but the ledes seem to be somewhat accessible. Those ledes have very little content though, probably not meeting WP:LEDE in terms of giving a stand-alone summary of the article. — Carl (CBM · talk) 15:58, 15 February 2011 (UTC)

Where does the "8th grader" reader concept come from? I'm not familiar with your school system but that appears to be around 13 years old. I think it is more reasonable to expect a bright 13-year-old to be willing and able to read material aimed at adults than to expect adults to want to read material aimed at 13-year-olds, or our editors to write down to that level.
I'm a wee bit concerned we're dismissing articles like Hydrochloric acid and Acetic acid because they [edit]not "particularly advanced topics". Those are the very type of article this guidline should hit 100% as they could be over-technical but there's really no reason to make them so and doing so would deny many readers a topic they deserve to be able to understand. If we go round trying to find impossibly complicated topics, then we'll end up back where we were before -- dismissing the guideline as unworkable. The edge cases must not drive the guideline, though the guideline needs to be aware of them and hopefully deal with them without editors having to invoke WP:IAR. Colin°Talk 16:21, 15 February 2011 (UTC)
I'm sure I said that the two acid articles were not particularly advanced topics. — Carl (CBM · talk) 16:38, 15 February 2011 (UTC)
Typo. Colin°Talk 21:03, 15 February 2011 (UTC)
I prefer to say "8th grade" because "general reader" is even more vague; the general reader for one article is likely to differ greatly from the general reader in another article. I have often heard that a typical American adult has an 8th grade reading level (or less), so I picked that number. In other words: to write for a typical American adult, you need to pretend you are writing to an 8th grader. If you have a different concrete suggestion for who a "general reader" is, let me know.
In my experience, the articles that people complain about in terms of inaccessibility are not ones like sun, star, or addition. Everyone agrees those need to be written with a grade-school audience in mind. Traditional encyclopedias like the Encyclopedia Britannica focused on topics like these; try looking up an more advanced topic there and you'll see what I mean.
The complaints that I often see are about articles like rhodocene or exterior algebra, which are studied only in more advanced contexts. One of the fundamental strengths of Wikipedia is that we go far beyond traditional encyclopedias to cover topics that were previously only covered in graduate texts and journal articles. In this way, we are already making human knowledge far more widely accessible than it was in the past. But there is a limit to what can be achieved, particularly given that we are not trying to be a textbook and we have to stick very close to the published sources on a topic. If every source on a topic is at the graduate level, we can often make our article accessible at the advanced undergraduate level; but getting it down to the 8th grade level is much less feasible. — Carl (CBM · talk) 16:38, 15 February 2011 (UTC)
The worry I have (and I've seen this) is people saying "there's no way I could explain this to a 13-year-old". And so give up. I wonder what level a magazine like New Scientist pitches its writing at? Does it expect its readers to have a degree? It certainly doesn't expect them to have a degree in the subject. That's the level I think many articles could achieve without too much effort. Colin°Talk 21:03, 15 February 2011 (UTC)
Someone writing for the New Scientist has a lot more editorial freedom than we do, though - they can make unsourced analogies and invent examples, for instance. — Carl (CBM · talk) 21:19, 15 February 2011 (UTC)
There is absolutely no reason why the leads of advanced topics cannot at least address the topic in a manner that the average reader (which I've always presumed has a LCD of being a grade-school student) can at least come to appreciate why the topic is important. The body can go as technical as possible (though arguably I think there are ways to write bodies in a similar manner to start broad and narrow to details, but let's not worry about that now), but the lead should be understandable by any of our average readers. This doesn't dumb down advanced tech articles, because the bulk of the article can still be written from a higher level. --MASEM (t) 16:45, 15 February 2011 (UTC)
I think the question is what does "the average reader can at least come to appreciate why the topic is important" mean. Does Aldol reaction do that? Poincaré conjecture? What is the most advanced topic for which you can find an article that does that? I think that my concern, as someone who often works with technical articles, is that the guideline is quite vague about this. Of course everyone agrees that each article should be as accessible as reasonably possible, but on its own that doesn't mean very much. — Carl (CBM · talk) 16:51, 15 February 2011 (UTC)
The aldol reaction lead doesn't quite do it. It doesn't readily answer the base questions, though the answers are suggested but sort of off-hand nature (The "why", to me, is that this process is common in the production of many pharmaceuticals and other compounds where the 3D arrangement of the atoms in the molecule is critical.)
The Poincaré conjecture is better but still misses a larger question. That is, the visual and simple english of what the conjecture is is explained, and clearly there are people interested in its solution ($1M prize), but again, the why doesn't seem to be there.
Neither of these are that far off, as compared to rhodocene, for average reader comprehension. --MASEM (t) 17:02, 15 February 2011 (UTC)
Is there any article on a technical subject that does meet that goal? If nobody can point out an article that actually does what the guideline suggests, that makes me think that either the guideline is out of touch, or people are interpreting it too strictly. — Carl (CBM · talk) 17:22, 15 February 2011 (UTC)
Enzyme inhibitor, an FA. The lead is written to a layperson (avoiding specifics of what the inhibitors are, but explaining why they work and why they are important) without being condescending to the reader. I note features of the 3rd para of the lead where technical terms are explains in parenthetical phrases, --MASEM (t) 17:55, 15 February 2011 (UTC)
Thanks. If that is the sort of thing that people are looking for, it can certainly be achieved in many articles. I would have been afraid that sentences like "The binding of an inhibitor can stop a substrate from entering the enzyme's active site and/or hinder the enzyme from catalysing its reaction." would be too advanced for a general reader. — Carl (CBM · talk) 20:17, 15 February 2011 (UTC)
It has lots of the hallmarks of writing that is really making the effort. But I'd agree with Carl about the "substrate" sentence. The general reader won't have a clue what a substrate is. The third paragraph could take things a little gentler too. But I think it is entirely possible to make that lead fully accessible to the general reader. Colin°Talk 21:03, 15 February 2011 (UTC)
I'm not trying to be difficult here, but I really don't see anything wrong with the third paragraph there. Do you have any article that you think does make the cut? — Carl (CBM · talk) 21:19, 15 February 2011 (UTC)
"Substrate" is possibly the hardest word there, but a brief bit of text - say "The binding of an inhibitor can stop a substrate (a chemical compound) from entering the enzyme's active site..." - is sufficient to clear that up. The point I'm trying to make is that that lead is certainly accessible but does not belie the content of the article, which gets much more technical after that. That's an ideal roadmap for how technical articles should be written. --MASEM (t) 21:41, 15 February 2011 (UTC)
I thought the lede was fine, but I expect that the people who are most pushing for clarity will say that it's not actually clear enough. The real difficulty is that "clarity" is quite subjective. I find the third paragraph, in particular, to be crystal clear, but apparently Colin doesn't. — Carl (CBM · talk) 21:49, 15 February 2011 (UTC)
This is probably where we need to step in and recognize "what is the lowest common denominator that we should write to?" and use that as a fuzzy line. We could say, impractically "kindergarten level", but that's pretty much impossible to write to, and even if we succeed, the saccharine language needed would be insulting to higher readers. This is why I do like the idea of an 8th grade / 13 yr old reader as a basis. At least in the states, by then: they have been introduced to the concepts of algebra and higher maths, they have had rudimentary chemistry, biology, and physics courses, a broad review of world history, geography, and politics, and several other subjects. They probably wouldn't be able to make heads or tails of a journal article that is highly technical but can probably understand writing from Discover, Scientific American, and the like. And like the example lead above, they should be able to understand that. That's about as low an education level we can go to make it possible to write clean, understandable leads that don't oversimplify the technical aspects or treat our readers unfairly. --MASEM (t) 22:10, 15 February 2011 (UTC)

I usually try to write one level down. So I think of articles on basic topics as written for 8th graders, articles on undergraduate topics written for high schoolers, and articles graduate topics written for undergrads. I have always though that was a reasonable way to do it, and it can be achieved without belittling the reader (which I think that parenthetical comments and simplified prose often do) or going into original research or textbook-like prose.

I think the lede of enzyme inhibitor is just fine, in terms of accessibility. If someone is seriously struggling to read that, they really need to look at some of the links before moving on to the rest of the article. There are articles that are seriously inaccessible, but that's not one of them. — Carl (CBM · talk) 22:22, 15 February 2011 (UTC)

Your approach of "writ[ing] one level down" sounds pretty reasonable-- would that be something worth mentioning on this page? SandyGeorgia (Talk) 00:10, 16 February 2011 (UTC)
I would agree that the starting point for the entire article should be "one level down" - as a tertiary source, we're summarizing something and that means we don't need to go into hard details. That means, like as shown for enzyme inhibitor, which would be something at an advanced or specific degree, the next level down is general college chemistry/biology, which I feel it covers right. The rhodocene article is where the bulk of the article is still at the advanced level (grad-level organometallic chemistry), but could be written down to college-level chemistry.
But I still believe the lead itself should be written to some LCD expected for readers (eg my 8th grade analogy). From the standpoint of a reader that might only have high-school education coming across a term that they want to figure out and is beyond a dictionary definition, a simple lead does a world of wonders for them, while the rest of the article still serves the larger group that would likely use the article in the first place. Outside the lead, I don't think we can expect all tech articles to maintain clarity at the low level, and I do like the one-level-lower approach for that. --MASEM (t) 00:18, 16 February 2011 (UTC)
I also very much like the "one level down" principle as a starting point for the entire article, and quite likely the goal for the bulk of the article. This is at least as good a "Rule of thumb" as the ones currently listed, and I support adding it to the guideline. In response to Masem, we should certainly aim to do better than that with some or all of the article, especially in the lead, but there might also be parts of the article where we can't go one level down and remain encyclopedic. Flexibility is the key. Geometry guy 01:02, 16 February 2011 (UTC)
Maybe even then at least the initial part of the lead should be at the LCD level, if it is truly the case that the best summary of the article requires higher technological discussion. Build from the general to the specific. I would think, even for a highly technical topic, that is always possible to write one sentence to the layperson as to why people (not necessarily the reader themselves) care about this topic. Take the example Diagonal lemma given above. I probably would have a hard time understanding the topic, but the lead begs the question "So what?" which I think could be answered in one or two sentences at the start of the lead and then move on to the language "one level down" (eg college level modern algebra/set theory) for the rest of the lead and the article. --MASEM (t) 01:18, 16 February 2011 (UTC)
I also support the idea of "one level down" as a reasonable approach to the whole article (with reasonable exceptions); however, I'm not convinced that anything really needs to be written at the 8th grade level. This comment, for example, scores at the 12th grade level. WhatamIdoing (talk) 05:08, 16 February 2011 (UTC)
Clarifying (to some extent) what we mean by "general reader" would be helpful. The average adult has a very low reading level, 8th grade or less, according to everything I have ever seen. So if "general reader" means "average adult" then we would need to write similar to Reader's Digest to reach them. I have always thought that certain articles about very basic topics should be written in this way, at least in the earlier parts of the article. — Carl (CBM · talk) 12:37, 16 February 2011 (UTC)

Angiomyolipoma

Ok. I'll pick an example I'm familiar with: Angiomyolipoma. We start off badly with an article name that is too long for most people to pronounce easily. Let's look at the original lead sentence:

Angiomyolipoma is a benign renal neoplasm previously considered to be a hamartoma or choristoma, but now known to be benign.

The "renal" and "neoplasm" will trip up many but not all lay readers and "hamartoma", "choristoma" will befuddle most physicians. MedScape is a little better with:

Angiomyolipoma is a benign renal neoplasm composed of fat, vascular, and smooth muscle elements.

The "vascular" adjective might not be familiar to many. At least they've got rid of "hamartoma" and "choristoma". GPNotebook is awful:

Angiomyolipoma is an important hamartomatous, benign renal parenchymal tumour.

There. It is important. We told you so. My medical reference book has this impenetrable nonsense (as far as any lay reader is concerned)

Angiomyolipomata, once classified as hamartomata or choristoma, are now classified as PEComas (tumors showing perivascular epithelioid cell differentiation).

Here's the current text:

Angiomyolipoma (AML) are the most common benign tumour of the kidney and are composed of blood vessels, smooth muscle cells and fat cells.

The precise classification is really of interest only to specialists and contains some pretty difficult material so I've left that out the lead. I cover it as best I can in the Classification section (which possibly could go later). What the above shows is that it is perfectly possible for experts to write impenetrable nonsense on an obscure subject but it can be rescued by following the guidelines here. Colin°Talk 18:26, 15 February 2011 (UTC)

I agree with your changes. The only thing I would add, as you mention it, is how to pronounce it as a non-standard English word. But you're exactly right in the point that a highly technical topic can be introduced in a simplified manner. --MASEM (t) 18:55, 15 February 2011 (UTC)
While I think that Colin's changes are an improvement, I don't actually think that the original first sentence was incomprehensible. I admit that I know what the adjective "renal" refers to, but I did not know the words "neoplasm", "hamartoma", or "choristoma", but that's ok, I clicked on them and found out within one or two sentences of each of the articles. One thing worth pointing out is that tumour is jargon, it just so happens that it has entered everyday language because everyday people get cancer every day. Similarly, "kidney" is a technical term. But we all have kidneys, so we all know what they are (of course, almost all of us don't really "know" what they are, we are just familiar with the fact that they exist within us, are vital organs, and are called "kidneys"). But a whole other thing happens with the vast majority of math topics, for example, where the basic objects discussed have no basis in any common person's life, nor do any of the things they apply to, or any of the things they are related to. In those cases, I think that it is a detriment to the article to attempt to make up some surrogate language or explanation of the topic; one specific way that it decreases the use of the article is that any visitors to the article who actually have approximately the right background to understand the lede will not understand some vague awkward lay-ification of it.
Full disclosure: like Carl, I'm a mathematician, so maybe I'm more used to setting words as variables and looking them up later. Or maybe, it's that I've learned through experience that despite my brilliance (heheh) and high-level of education, I can't possibly expect to understand any giving thing the first time around (or even the tenth time around) no matter how well it's written. Why do we think people should understand the first sentence so easily? Some things are difficult. RobHar (talk) 03:18, 16 February 2011 (UTC)
Well if you didn't know what a neoplasm was, and like 99.99% of the world don't know what a hamartoma or choristoma is, then the lead doesn't tell you want the article topic is. So how could it be not "incomprehensible". If to comprehend the sentence you have to click on the links (and many of us editors have PopUps so this sort of thing is less disruptive than for our actual readers) then it was only comprehensible after you read some articles. If you have to read three other articles to understand the lead of the first, that isn't a very efficient experience and I bet you wouldn't continue unless you had a special interest in the subject. I disagree that "kidney" is a technical term. A five-year-old knows what a kidney is. Words like "tumour" cease to be jargon when one expects the everyday person, outside of the discipline, to both know and use the word comfortably. Colin°Talk 08:02, 16 February 2011 (UTC)
You do not need to understand what every word means in order to comprehend a sentence. Exhibit 1: Jabberwocky. Exhibit 2: If I tell you that "I saw James G. Flien yesterday", you can understand that even though you don't know who the person is. Exhibit 3: If I tell you "Carbaryl is a chemical in the carbamate family used chiefly as an insecticide", you can comprehend that without knowing what Carbaryl is or what the carbamate family is.
I think this fallacy (every word has to be understood) underlies some naive complaints about accessibility. For technical prose, the reader has to treat unknown words as undefined constants, rather than stressing about what they mean. There is nothing inaccessible about the sentence "Carbaryl is a chemical in the carbamate family used chiefly as an insecticide". — Carl (CBM · talk) 13:48, 16 February 2011 (UTC)
I can work out that "James G. Flien" is a person and probably not the name of a film or TV show, but it might be. You tell me that Carbaryl is a chemical and that it is used as an insecticide. You are right that I didn't have to know what "carbamate family" meant and someone has to make a judgement call as to whether that classification (a) would mean anything to the general reader even if explained (b) can be held off explaining till later or (c) is a detail the lead doesn't need. In the original text, if you didn't know what a neoplasm was or a hamartoma or a choristoma then I could have been talking about fungi or aliens. Having "carbamate family" in the lead reduces its friendliness as the reader is starting to get a little uncomfortable that the article is at his level. To do that so early on is not great. But it isn't a fatal mistake. If all the lead sentence said was "Carbaryl is a member of the carbamate family." then that would be bad and inexcusable. Colin°Talk 15:01, 16 February 2011 (UTC)
It would be bad but it would not be inaccessible, which is the subject of this guideline. We can't cover every type of bad writing here. There really is inaccessible text – paragraph-longs sentences where I can't even identify the verbs, where I have to rewrite the sentence just to figure out what it says. "Carbaryl is a member of the carbamate family", along with the context that Carbaryl is a chemical (not nobility) is not "inaccessible", even if I don't know what the carbamate family is (which I don't). — Carl (CBM · talk) 15:11, 16 February 2011 (UTC)
(ec) Are we assuming our readers are incompetent? That they can't click on things? I did not have to "read some articles" to understand the former opening sentence of Angiomyolipoma, I had to read 1 or 2 sentences from each of 3 articles, it was no big deal. And, no, five year olds don't know what kidneys are. They may very well know the word, but do they know what kidneys do? Probably not. For example, I just learned that they help regulate blood pressure. Who knew? And what is the technical term for kidney? It seems that what is wanted here is to provide the readers with words that they are comfortable with, not necessarily words that they actually understand, just words that they feel that they understand. And that's a good idea, it certainly helps to understand a sentence or a paragraph when the words used are familiar, and I support this goal. But I believe that this goal is being conflated with the goal of making the sentences not just feel more understandable, but be more understandable. So, when you're lucky enough that you've found an article where unnecessary jargon like "renal" is used, and you can replace it with an equally technical term that just so happens to also be a common term, like "kidney", it somehow seems like one should be able to accomplish such a thing in a more general collection of articles. But there is no equally technical, yet also common, term for Galois cohomology, or any of the objects it pertains to. So, you can't make the kind of superficial (but indeed helpful!) change like the one from "renal" to "kidney" or "hamartoma" to "tumour". Here's an anecdote that alludes to the type of thing I'm trying to highlight: one time, I spent about 45 minutes arguing with a philosopher on the topic of what thoughts are. He was drawing some conclusions that I just didn't think were there, so I argued against him. This went on until I realized that he was using the term "thought" in a rather restricted technical sense. He never mentioned this, I don't think he ever realized that he wasn't speaking actual English, but rather some form of technical jargon that just so happened to use common words to refer to approximately the same thing as they commonly refer to. When you're speaking to a philosopher (and he/she manages to avoid words like hegemony and hermeneutics) you may feel like you understand what is being said, but there's a whole world of implicit technical meaning you are not getting. I think that the policy page under discussion (or the "essay" that it is now?) should address the issues I've raised. All too often, people show up at math articles asserting the math editors are disregarding this (and related) policies because they simply don't know the difference between feeling more understandable and being more understandable, and the difference between overly technical language and necessarily technical language. RobHar (talk) 14:31, 16 February 2011 (UTC)
We have a policy against requiring readers to follow links to understand a sentence, especially in the lead. It is more impatience and attention span we are fighting against rather than ability. As my user-page quote says "It is our job to interest [our readers] in everything. It requires the highest degree of skill and ingenuity". The lead is the place to grab their attention and you will not grab it by using words they need to look up. I suspect many editors here are much more willing to invest effort in understanding an article or the books they read than the average reader. We are not average readers.
There is a range between fully understanding something and merely getting the gist of it. For the lead, we don't need to achieve the former but we should to do better than the latter, and if we haven't done the latter then we really have failed. You don't need to fully understand what kidneys do in order to know this article's lead: they are a bodily organ and this is a tumour in one or both of them. Colin°Talk 15:01, 16 February 2011 (UTC)
The same policy prohibits writing that are meant to teach the subject to the reader. Explaining the meaning of every term in detail would break that part of the policy. So we have to balance those two goals. In reality, articles do teach some things, and do require readers to follow links for information about other things. — Carl (CBM · talk) 15:11, 16 February 2011 (UTC)
Carl, WP:NOTTEXTBOOK doesn't outlaw explaining jargon or technical terms in simpler language. It doesn't outlaw explaining concepts or spending a sentence or two to give context. It says we shouldn't "teach" which is a different thing from "inform". It says we shouldn't have "leading questions and systematic problem solutions as examples", which clearly we don't. Textbooks may address the reader directly and ask them to consider something. They often have chapters in the "Say what we're going to say. Say it. Say what we've said." style that repeats material so that students might just remember it. All sorts of stylistic differences to a reference work. I think you are seeing a problem here that doesn't exist. Colin°Talk 15:28, 16 February 2011 (UTC)
The policy says, "The purpose of Wikipedia is to present facts, not to teach subject matter." On the other hand, the policy also says, one paragraph later, "A Wikipedia article should not be presented on the assumption that the reader is well versed in the topic's field." These two go together. On the one hand, our goal is not to teach a subject to someone who has no idea what's going on; readers who know nothing about a topic will need to consult actual textbooks to learn about it in detail, and they may well find our reference on it somewhat confusing. On the other hand, we shouldn't assume that the reader is well versed in the field when they start reading the article, and should try to fill in what we think are the immediate prerequisites. So our articles balance between the two extremes of assuming the readers know nothing and assuming they know everything. This is one reason I like the "write one level down" method, because I think it strikes a good balance. — Carl (CBM · talk) 15:53, 16 February 2011 (UTC)
Well, earlier you said "Explaining the meaning of every term in detail would break that part of the policy." and I disagree. That's not teaching, which is a specific style and method of transferring more than just a collection of facts. Teaching also tends to have from-the-ground-up approach. With our articles, we can't just say "Hold on. You can't read this till you've read "Elementary Renal Medicine" and you mustn't read this chapter till you've done the first three. Instead, we need to fill in enough of the blanks and gaps in the reader's knowledge in order for them to understand just this one. How far down we expect the reader to be at is up for discussion. Colin°Talk 16:20, 16 February 2011 (UTC)
An article which starts with nothing and explains every term, from the ground up, until it reaches the actual topic of the article, is clearly trying to teach the topic to the reader, rather than merely providing a reference about the topic. That has never been the way that Wikipedia articles were written, so it cannot be what WP:NOT is trying to say. Now, I don't think that either "don't teach at all" and "don't assume any background at all" is accurate. The real policy that everyone follows is that we shouldn't go to far in either direction. — Carl (CBM · talk) 16:58, 16 February 2011 (UTC)
If I may, explaining every term in every article is a problem for another reason. Suppose there were explanations from the ground up in articles on kidneys, on renal function, on various renal tumours, on kidney diseases, and on kidney transplant. Suppose further that a reader is looking for information because s/he does not understand his or her doctor so reads several articles. Won't all the repetition get more than a little irritating and redundant? Won't it also produce a lot of bloated articles? Assuming that the topics I have just made up all have separate articles, wouldn't there be a lot of overlap in the "one level down" info in each of them? I'm not suggesting that some explanation isn't both appropriate and desirable, but some of the suggestions here seem to me to go further than seems wise. EdChem (talk) 22:46, 16 February 2011 (UTC)

Rhodocene

I didn't see this whole kerfuffle, here, but r-cene is not a good example of a topic that can't be better explained in lead. Sure there might be topics in the loftiest echelons of math where that might be true (but even there, give it a fighting man's TRY first). I gave comments in the talk page for how to improve that lead. The rewritten (see talk) lede already progresses to comprehensibility.

I mean, when someone like Sasata, a practicing biologist Ph.D. with biochemistry understanding, and more tolerant of scienceyness than a lot of people, says the article gave him pause we should listen. There was a material scientist who had the same reaction. And I have a Ph.D. in inorganic chem. And I say it can be dialed down in the lead! I mean someone who is an engineer or a scientist should be able to get some feel for the thing, and a bit more pleasantly. But as of now, it's at least at Greenwood Chemistry of the Elements level of diffuculty (a general reference for inorganic chemists). I mean, it should be accessible by a chemical engineer at Dow or whatever. Not just grad students of Cotton. Some of the stuff is simple, like dialing down redundant use of chemical formulas (when names serve the need).

So please don't hold up rhodocene as the case where it's just too impossible to communicate. It's more the example where we didn't give it enough of a try! For one consideration, realize that the author has not shown other articles where he did do an FA (or even just an article) where he did the task of translation to civilians. Again, not to beat the fellow up, he is very reflective. The author was very willing to listen to my comments (and is probably a better chemist, writer, and nicer guy than I). But my point is, if I see someone who HAS translated a lot of technical stuff successfully, and then he says "this one is just impossible", then it's a point in favor of the assertion. OTOH, when he hasn't done that, it's more likely that he just needs to take a strain and learn to make articles accessible.TCO (talk) 20:50, 15 February 2011 (UTC)

Plus, there is the body of the article where we can go more technical, so we're not shutting that content out of WP, per se...just the lead. And then even in the article, there are a few tricks that can be done to front-load sections (or parts of sections) that are more accessible first. For instance more on applications, discovery, context in the field...first. Then further back stuff on the details of a math proof, or some quantum orbital stuff. And yeah...you can't always do that, but sometime ya can.TCO (talk)
It's better to avoid the word "needs". Nobody is forced to do things, and the article is not in "bad shape" in any way. What has happened is that people are looking for additional goals above and beyond the usual goals of providing an encyclopedic reference article on a topic. That's a fine aspiration, and worth talking about. But the actual content requirements don't require anyone to "take a strain", and the article as it is written is perfectly in line with the usual way that these articles are written on Wikipedia. That's not to say that no improvement is possible - but it's not necessary. — Carl (CBM · talk) 21:36, 15 February 2011 (UTC)
I understand your point generally, but if it wants to remain an FA, where it will most likely be featured on the mainpage, yes it "needs" to be fixed. And the good news is that it sounds like progress is being made (I haven't looked at talk). SandyGeorgia (Talk) 21:55, 15 February 2011 (UTC)
But it doesn't need to remain an FA. The FA project in general is an independent group, like a WikiProject, that marks some articles as "Featured articles" and selects articles for the main page. In general it's not necessary for editors to worry about the internal requirements of the FA project, the are free to simply ignore FA entirely. There's nothing about FA that would support the claim that an editor "just needs to take a strain and learn to make articles accessible" (which is quite belittling). — Carl (CBM · talk) 22:13, 15 February 2011 (UTC)
I still disagree. While 99% of the Wikipedia may be out-of-policy junk, FAs must comply with policy; e.g., WP:NOT. SandyGeorgia (Talk) 00:10, 16 February 2011 (UTC)
WP:NOT also says that our articles are not textbooks – "The purpose of Wikipedia is to present facts, not to teach subject matter." The goals of being a reference work (not a textbook) and being accessible (not too arcane) balance against each other.
The exact language in WP:NOTPAPERS that you're focusing on has never been particularly accurate for technical articles, where we generally do, in fact, assume that the reader is somewhat familiar with the field of the article. We don't assume the subject is well versed in the field, but we do assume some familiarity. The language in WP:NOTPAPERS is accurate for the majority of articles, for sure, but like all Wikipedia policy it has to be read with a knowledge of how things are actually done. — Carl (CBM · talk) 00:36, 16 February 2011 (UTC)

I was unaware that the rhodocene atricle was being discussed here until earlier today, and have just read this discussion (including the above sections). As I have said elsewhere, I have no problem with working on improvements (preferably in response to constructive feedback) and don't WP:OWN the article. Perhaps this discussion might be directed at other examples, accepting that there is a talk page for the article and that these meta discussions (while necessary in their own right) are unhelpful to the specific case. Just so SandyGeorgia is aware, I have no intention of nominating the article for TFA anytime soon, possibly never at all. In part, it is because the article is never going to be a topic of wide interest and many other more general topics are more deserving of that kind of spotlight. As a personal observation (to all), I am upset that my "achievement" in getting the article to FA and the brief period of pride I felt has been so tainted and I urge that editors in the future consider that the pseudonym(s) who wrote the article (however much you dislike the writing and content) represent real people. There is no harm in treating others with compassion and acknowledging our common humanity. EdChem (talk) 11:32, 16 February 2011 (UTC)

Essay

If this is to be elevated to style-guide status, there should be explicit consensus. I see issues all over the page. For example:

  • "consider using [jargon] sparingly thereafter, or not at all". This is not always good advice.
  • "Eliminate long strings of adjectives, particularly technical adjectives."—an example so we know what it's talking about?
  • "Comprehension decreases dramatically when sentence length exceeds 12 words."—reference for this claim?
  • "Use more verbs to improve readability — you can replace many technical adjectives with verbs."—examples? I'm unconvinced.
  • "Use language similar to what you would use in a conversation."—Bad bad advice.

Just at a cursory glance. Tony (talk) 04:17, 16 February 2011 (UTC)

On your first point: The fact that it is not always appropriate to exclude jargon is why we tell editor to consider it, not do it, without exception. WhatamIdoing (talk) 05:19, 16 February 2011 (UTC)
In general, that applies to all the above comments. This is not a MOS, but more a content guideline. All the advise given is common sense advice geared towards best comprehension of topics. --MASEM (t) 05:21, 16 February 2011 (UTC)
On the second point, sentence length is a major determinant of reading levels. The other significant factor is how hard the word is considered to be (measured either by characters, syllables, or a check list of allegedly difficult words). Different scales weight things differently, but in general, the longer the sentence, the "less comprehensible" the writing is (on average). For example, my "12th grade" comment above is only a 10th grade comment if you replace the semicolon with a period, because the average sentence length drops dramatically when you turn the sentences into three. Whether 12 is the magic number is not something I can verify, but I suspect that the magic number is less than 16 or 18. WhatamIdoing (talk) 05:27, 16 February 2011 (UTC)
I'm suspicious; what about the insertion of a semicolon in the middle of a longish sentence? Does that count as two sentences or one?
Long sentences are often undesirable irrespective of "reading level" or technicality. Tony (talk) 06:38, 16 February 2011 (UTC)
Try it yourself, and see what you think. The web systems aren't smart enough to differentiate between two independent clauses joined by a semicolon and a complicated list in which the semicolon functions as a serial comma. This comment, which contains no semicolons, averages 11th grade level on the various indices, with a range of about 9th to 13th. WhatamIdoing (talk) 07:52, 16 February 2011 (UTC)

I just did a Google search on (sentence length technical writing). The 12 word thing is extreme, although that's what advertising copy aims for. In general there is discussion of the "fog index" which has to do with adding long words to long sentences. Basically if you're already making it hard with long words, then compensated with shorter sentences. Shorter paragraphs are also advocated. Reference is made to D. H. Menzell's study of sentence length comprehension, but I have not been able to get the original source for the study. but supposedly over 34 words in technical writing is incomprehensible. There is discussion that some long sentences are allowed but the average should not be too long. US military advocates 17 words average.

Obviously more could be dug into, and I really respect those who know more about this than I. I just surfed Google and am a fan of Katzoff (he also advocates short sentences and paras in technical writing). Again, admitting we should look for more sources, would just say that the important thing is to realize that what's OK in an article in biography or history (with a narrative and easy words) is not the same as in an article where the material itself is more of a strain (more abstract). For instance in math or physics it is a bad idea to BOTH add new notation and new concepts. One at a time. But the combo is painful. Similarly, I think going with shorter sentences and shorter paras when the content is trickier, just makes sense. But Tony is right to ask for RSes!TCO (talk) 07:05, 16 February 2011 (UTC)

P.s. My google surfing said you could treat the semicolon as making it a new sentence for fog index.

P.s.s. Obviously too long of a sentence can be an issue on its own, but to Tony's point, I think when the words are simple, from childhood, then it's easier than if they are trickier adult ones, or really sprecialized ones.TCO (talk) 07:05, 16 February 2011 (UTC)

I think Tony is right to want to buff up the article. I do broadly agree with the article's point. But buffing it up with more facts and discussion would be great.TCO (talk) 07:52, 16 February 2011 (UTC)

Tony, I'm most surprised and annoyed by your revert over the guideline status of this page. The edit summary of "Rv unilateral granting of MoS status until consensus is gained" is not only hypocritical but wrong. There was clear consensus at WT:FAC for this to be restored and you were the person who unilaterally revoked its guideline status. When later an RfC was invoked to question the move, the result was no consensus for the change and some strong words criticising your actions.

Perhaps this should be restored to guideline status as a content guideline than a MoS guideline. It is far more important than where to put the semicolons and whether to use italics. It doesn't matter if every sentence in this page offers perfect advice today. We don't revert WP:V every time someone adds a sentence or SV rewrites it in order to get copy-edit approval from the MoS police before it can become policy again. If Tony has a problem with a few sentences, then remove those sentences and discuss them here. The main point of the guideline is vital. Colin°Talk 08:17, 16 February 2011 (UTC)

Was I aware there was an RfC? Where is the link? This was part of a long-overdue mini-effort to rationalise the sprawling MoS. What I see on this page is a lot of essay-type stuff, some bad grammar, and a few good points. Rather than pump this little page up to MoS status again, why don't we agree on what is useful and uncontroversial in it and put it in the MoS main page itself? Tony (talk) 08:22, 16 February 2011 (UTC)
The RfC I refer to is the one just a bit further up this page. I couldn't give a stuff about "a mini-effort to rationalise the sprawling MoS". Procedural MoS stuff is not important compared to a guideline that desperately needs highlighting. At present, the rump of this guideline exists on the MoS page sandwiched between "Color coding" and "Scrolling lists and collapsible content". This is about more important stuff than where the semicolons go.
Let's get it out of the MoS so you don't get upset about having a few sentences wrong. Let's just make it a content guideline. Please just take out the few sentences you have the most problems with and undo your unilateral action (for the second time). Colin°Talk 08:35, 16 February 2011 (UTC)
Why are you so insistent that this be reinstated as a little castle in the countryside? Editors are much more likely to refer to it if it's expressed succinctly in a few points in the MoS main page. MoS is too sprawling. Tony (talk) 09:58, 16 February 2011 (UTC)
Actually, I'd prefer if it was Wikipedia:Manual of Style (technical) or similar. But it seems that entry to the MoS demands perfection and ignores consensus. The MoS main page is a six-thousand-word monster and sandwiching advice on who we are writing for and how to achieve it when things get technical into a few lines near the bottom between "Color coding" and "Scrolling lists and collapsible content" is a joke. This page can be improved, and I've got some content I want to add myself. Your opinion on MoS sprawling is noted but mustn't get in the way of consensus that this should be a guideline. It was a guideline for five years before your unilateral rationalisation. There was no consensus to remove it and there is a consensus to reinstate it. You are acting alone, Tony, and I think you need to accept the opinion of others here. Colin°Talk 10:49, 16 February 2011 (UTC)

I support the content guideline. TCO (talk) 10:09, 16 February 2011 (UTC)

The idea of making it a content guideline, to avoid the sprawling mess of MOS, seems worthy, but the fact remains that it was a MOS guideline for five years before it was unilaterally demoted by Tony1 with no consensus. SandyGeorgia (Talk) 13:03, 16 February 2011 (UTC)

Improper reversion and demotion of guideline

User:Tony1 has, for the second time, unilaterally demoted this long-standing guideline to an essay with a curious edit summary referencing "unilateral granting of MoS status".

I'll requote Colin's summary of the history of this page from WT:FAC:

QUOTE

From April 2005 to April 2010, Wikipedia had a content guideline Wikipedia:Make technical articles understandable. This stated "Articles in Wikipedia should be accessible to the widest possible audience. For most articles, this means accessible to a general audience." Throughout this time, you would hear people repeat "Wikipedia articles are written for the general reader" just as often as "The threshold for inclusion in Wikipedia is verifiability, not truth" or any other well-known widely accepted rule. This guideline has an equivalent in policy at WP:NOT which (since July 2008) has said

A Wikipedia article should not be presented on the assumption that the reader is well versed in the topic's field. Introductory language in the lead and initial sections of the article should be written in plain terms and concepts that can be understood by any literate reader of Wikipedia without any knowledge in the given field before advancing to more detailed explanations of the topic. While wikilinks should be provided for advanced terms and concepts in that field, articles should be written on the assumption that the reader will not or cannot follow these links, instead attempting to infer their meaning from the text.

Then, in April 2010, the guideline was demoted to an essay without prior discussion. The reason for that demotion given here was that because we had some "highly technical articles that are pretty tough going for the non-expert" (i.e., impenetrable to the general reader) and "some of these are even Featured Articles", and a Mos guideline is "mandatory for FAs to follow", this conflict should be resolved by eliminating the guideline. So now, Wikipedia has no official guideline as to its audience level. And all because we promoted some articles to FA that clearly broke the guideline.

UNQUOTE

This page was a guideline for five years and was summarily demoted to an essay by Tony1 with no discussion, and then again based on an RFC which showed no consensus for that demotion, and now again after extensive discussion here and at WT:FAC. If Tony1 wants to demote it, he needs to gain consensus. That the writing can be improved is not a reason to demote a long-standing guideline to an essay, based on Tony1's personal preferences and observations about some FACs which he says have passed without conforming (see WP:OTHERSTUFFEXISTS, FAs which may have passed do not determine policy or guideline).

Also, will Tony1 please explain by what community process he believes he was appointed to "audit" and unilaterally remove long-standing guideline pages? And curiously, Tony1 indicates he wasn't even aware that there was an RFC (on this very page) that shows no consensus to demote the guideline, so what kind of "audit" did he perform before demoting the guideline? That the writing can be improved here is a distraction from the matter, and not a reason for demotion.

Finally, without highlighting previous cases, I'd like to remind Tony1 to avoid edit warring against consensus. SandyGeorgia (Talk) 12:50, 16 February 2011 (UTC)

Sandy and I used to be close wikifriends ... for years. Now all I get is snarling and growling. Nothing I can do will please her. See, for example, her ungenerous comments at this week's "Features and admins" talk page. Something waiting for me around every corner. Tony (talk) 12:59, 16 February 2011 (UTC)
I recommend that you remove your personal attack and avoid personalization of issues here; the matter at hand is your unilateral demotion of a long-standing guideline. SandyGeorgia (Talk) 13:01, 16 February 2011 (UTC)
<sigh> Tony (talk) 13:08, 16 February 2011 (UTC)

Target audience

One major issue with this essay is that it fails to take the target audience into account. There is no such thing as a "general audience", and this naturally leads to confusion over what is too technical for a "general audience": some would like to see every article reduced to an 8th grade reading (and knowledge?) level. Others have a more realistic viewpoint that the target audience of some articles (Grothendieck universe) is likely to be very different from that of other articles (addition). I think that a content guideline on making articles accessible is a good idea, but it needs to take a realistic viewpoint and offer advice that will be helpful to editors that are actually writing technical articles, since at the moment it seems largely to be used to bully those very editors instead.

As any good style manual on technical writing will tell you, the most important thing one needs to do is assess the target audience. This should be a realistic assessment. For example, if it's very unlikely that anyone without at least a solid background in a university-level science curriculum will be reading the article (e.g., exterior algebra), then it is reasonable to take this as the target audience, but completely unreasonable to think that the article should (or even can) be brought down to a high-school level.

Recently, the section on articles that are unavoidably technical was removed. While I agree with the removal in principle, I also believe that some assessment must be made of the correct level of technicality in an article that would be appropriate to its target audience (the article exterior algebra is an example—this cannot and should not be made accessible to an 8th grader). I propose that, if the essay is to be taken seriously by more science editors, then it should be written with an eye towards serious sources on technical writing. Sławomir Biały (talk) 12:44, 16 February 2011 (UTC)

Perhaps it would be helpful if someone here would define what we mean by "unavoidably technical", particularly considering the discussions above; that may help us focus the page. The "one step down" proposal seems to be well received so far. SandyGeorgia (Talk) 13:01, 16 February 2011 (UTC)
If "one step down" means what I think it does, that that seems reasonable—if it can be made into something a little more concrete. Sławomir Biały (talk) 13:06, 16 February 2011 (UTC)
CBM's "one level down" idea is explored above in the "Example" section (sorry for using the wrong word, which makes it harder to locate :) SandyGeorgia (Talk) 13:14, 16 February 2011 (UTC)

I added a paragraph about "one level down" to the guideline. — Carl (CBM · talk) 13:50, 16 February 2011 (UTC)

The only thing I'd add to that is the justification for that; as a tertiary source, our job is not to enumerate information at the level of data it is presented with but at a broader understanding, linking and referencing more detailed works for further study if the reader should want it. But even without that advice that is a fine addition. --MASEM (t) 14:24, 16 February 2011 (UTC)
Yes, that was something I never thought of explicitly but it matches my reasoning for writing down a level. I added a sentence to the paragraph about it. — Carl (CBM · talk) 15:20, 16 February 2011 (UTC)

I think the "write one level down" is a good start but it assumes the topic is an academic one. I don't see that working for "Angiomyolipoma" or some mushroom. What about a stubject like "Jesus", which people learn in Sunday school but I'm guessing (haven't looked) gets onto pretty heavyweight theological issues. Perhaps this advice could be worded to specifically address academic subjects. How do we classify the reader level for other topics? Colin°Talk 16:23, 16 February 2011 (UTC)

It works for pretty much every subject. Two areas I'm familiar with : In video games, we don't describe the gameplay at a level that a gamer would feel comfortable with, but at a level that someone that's never played the game (the "one level down") can understand. In fiction, we write out-of-universe, assuming the reader is not intimately familiar with the work and subtle details in particularly long-running series. Similarly, the concept can be applied to "Jesus" where one level down is explaining who he was without assuming full knowledge of Christianity. The "one level down" is easy to describe for academic articles, but is an idea that can be approached on other topics as well. --MASEM (t) 16:31, 16 February 2011 (UTC)
I can sort of see what you are getting at but the actual wording says "where it is studied". Which repeats an issue with one of the "three questions" futher up. Some subjects aren't academic disciplines but something anyone might come across. I'm concerned someone might apply this rigidly. Say "angiomyolipoma" was only studied by post-medical-school physicians specialising in renal medicine. Is one level down a medical student, or a nurse, or someone who did biology at school? What about the reader diagnosed with it? I think there is still room for the WP:NOT PAPERS requirement of not assuming familiarity with the subject -- for these non-academic topics. Colin°Talk 16:46, 16 February 2011 (UTC)

I've revised the initial section to specifically cover the "Audience" aspect. This section is essentially setting out the facts that the rest of the guideline will offer advice on. So I've removed any specific advice from that section. If some of that advice is useful, we can incorporate it later on. Colin°Talk 22:23, 16 February 2011 (UTC)

Strategies for improving this page, whatever its status

Rather than sniping and bickering at me, Sandy, could we take a more constructive attitude? My first observation is that "Ideas for enhanced understandability" is not supportable in a style guide. It should be binned. Tony (talk) 13:06, 16 February 2011 (UTC)

Once again, please remove your personal attacks and avoid personalizing issues; the matter at hand is a long-standing guideline that was unilaterally demoted. That the page needs improvement is secondary; the constructive attitude would be to respect consensus and work to improve the page-- something that was well underway until you demoted the page a second time. Bringing your command of prose to bear upon the page, while respecting consensus, would be most helpful! SandyGeorgia (Talk) 13:16, 16 February 2011 (UTC)
Tony, if you want to have a discussion on this page "whatever its status" then would you be good enough to undo your unilateral revert. It is souring relations. If after all the discussion we realise that we've only got one paragraph of text we can agree on, and we actually discover the issue is so unimportant that it should be burried at the very bottom of a six-thousand-word guideline, then you can mark this as an essay and we'll accept the little rump at Mos. Colin°Talk 13:23, 16 February 2011 (UTC)
I do not believe it should be a separate enclave. The change in status was part of a move to rationalise the MoS that should, in my view, gather pace. I am first interested to see what parts of this odd page people think are worth salvaging and perhaps putting into the MoS. Your lack of good faith shows that you are more interested in proving some point than in improving the page. I do not feel remotely sour: you do. Please move on and be constructive. Tony (talk) 13:26, 16 February 2011 (UTC)
The only person proving a point was you, this morning. That you WP:OWN MoS. Now prove me wrong. Colin°Talk 14:23, 16 February 2011 (UTC)
While you may "not feel remotely sour", your commentary here is personalized and "sour" (now to include personal attacks and allegations of "lack of good faith" towards a diligent Wikipedia editor). The parts of this guideline that need work were being discussed before your unilateral revert, and progress was being made. Specifically, I would like to see the importance of an accessible WP:LEAD retained regardless of whether the article is graduate level material (all readers should be able to digest the LEAD, and it is used to craft the TFA blurb that runs on the mainpage and should serve our general readership). Again, CBM's "one level down" idea seems worthy of discussion as well, so that we can define different categories of readership, while not writing impenetrable leads like we now have at rhodocene-- those will not serve our general readership in a TFA blurb on the mainpage. Staying on topic and discussing content, not editors, is always a good approach. SandyGeorgia (Talk) 13:36, 16 February 2011 (UTC)
I think we need to keep this discussion independent of the FA group and the Main Page. This is about accessibility of all articles, not about the few articles that go through the FA process. The FA group is free to impose higher standards on their articles without referring to this guideline at all. On the other hand, people will refer to this guideline even for C-class articles, or for articles that have never been nominated for FA. — Carl (CBM · talk) 13:40, 16 February 2011 (UTC)
Agree-- we seem to have gotten off on that track because the original demotion of the guideline was based on the allegation that some FACs had passed that did not meet the guideline, and FAC does not determine guideline or policy-- it should reflect it, as should all articles. SandyGeorgia (Talk) 13:45, 16 February 2011 (UTC)

Consensus

Am I right in thinking the only person who doesn't want this to be a MoS guideline as it stands, is Tony? Because if we just ignore that revert this morning then we are complicit in allowing consensus to be rejected and ignored. Twice. We need to work together to improve it on a consensual basis and that involves some respect for other opinions even if they disagree with you. If one person here has a golden vote over the wording or its status, then the Wiki model doesn't work. The purpose of these discussions is not to polish the page until Tony is happy or Colin is happy, or Carl or any one of us is happy. And it doesn't need to be perfect. Is someone brave enough to stand up for consensus? Colin°Talk 17:09, 16 February 2011 (UTC)

For me, the labeling of this article is far less important than the extent to which it reflects and clearly articulates consensus, rather than any one particular view. The label should follow naturally, whether as a MoS or a content guideline. Excellent progress has already been made: improvement, rather than tags, should be the focus. Geometry guy 00:28, 17 February 2011 (UTC)
To answer your direct question, I'm not brave enough because of the past ArbCom history-- I don't want to go there, but I agree that no one else seems to be opposed, and there was no consensus for the removal of the guideline, either time. Perhaps if anyone disagrees, they might speak up? SandyGeorgia (Talk) 00:31, 17 February 2011 (UTC)
Everyone knows perfectly well that this is part of a vendetta against me. By Sandy, it is revenge for daring to highlight the achievements of talented and hard-working Wikipedians at The Signpost's weekly "Features and admins" page—for indulging in "a culture of reward", as she puts it. By Colin, it is payback for the stance taken by Kwami and me last week concerning subprofessional typography, at the Medicine Wikiproject talk page. Tony (talk) 09:13, 17 February 2011 (UTC)
Tony, I have no idea what is going on between you and Sandy but it makes me very sad. I sincerely hope we can remain friends and not hold grudges. All friends rub each other up the wrong way, say things that hurt, find out they disagree on things held important, and all friends disappoint each other at times. Let's move on from this. As for the typography thing, nobody worked harder than me to find consensus between the two fundamentalist groups. I thought that Kwami and I had found a compromise that both of us were happy with but it seemed others wouldn't budge on their polarised positions. Ultimately, I felt it was truly ridiculous for people to get so worked up and fall out over a hyphen, hence the piss taking, which really was intended as a bit of fun and not to cause hurt (and I apologise if it did). I do not take revenge and this is not "payback". Both of us spend our time on Wikipedia with the aim of making it a better experience for our readers. We may at times disagree on the ways of doing that, but we are on the same side. I remain very annoyed over your action yesterday but I'll get over it. Can we move on and work together to improve this page. Colin°Talk 09:33, 17 February 2011 (UTC)

I'm fine with this being a guideline as it stands - but as editing goes forward, we need to keep the key aspects that:

  • We accept that different articles will achieve different levels of accessibility
  • The guideline does not somehow try to claim that the actual widespread practice, which we have been developing over years, is now deprecated.

I don't think the current text does either of those, so I can support it being a guideline. — Carl (CBM · talk) 13:35, 17 February 2011 (UTC)

Concur: regarding the first principle, the "interested reader" and "widest possible audience" vary from article to article; regarding the second, guidelines exist to reflect consensus on best practice, not to lead or change it (essays aim for the latter!). Geometry guy 22:14, 17 February 2011 (UTC)
I took the only useful stuff from this page and put it into MoS main page. That will have to come out of MoS main if this is to be evelated to MoS status. It is not fair to pile more text into an already-large MoS main page if there is no benefit in rationalising the overall structure. I will remove the text now. Tony (talk) 02:07, 18 February 2011 (UTC)
I don't think we can call this a MOS. It's a content guideline, but its not a rigorous statement of style to be a MOS. There is room for both the brief MOS section that does exists, and more guidance through here. (Again, see WP:WAF for how this could work). --MASEM (t) 02:39, 18 February 2011 (UTC)
I'm not quite sure what you mean by "I will remove the text now". I don't see any changes. I do think this belongs best in MoS rather than a general content guideline as many issues are style. I think Tony is saying that if promoted to a MoS guideline like WP:WAF and WP:LEAD then it would be best not to also have a summary section on the main MoS page (which neither of those two MoS guidelines have -- though it could perhaps retain a link somewhere). Considering that page is mostly about punctuation and is already too long, I don't have a problem with that provided we don't end up with a situation where it is neither mentioned on the MoS page nor is it an official guideline. I believe the concern with having the advice in full form and summary form is that they can get out of step and it means people have to read both page on overlapping topics. Colin°Talk 08:47, 18 February 2011 (UTC)
Should this page be renamed Wikipedia:Manual of Style (technical). Any other suggestions? Colin°Talk 08:49, 18 February 2011 (UTC)
You're jumping the gun. There's insufficient evidence thus far that this deserves to be a stand-alone page rather than a few brief points at MoS main. Convince us first. Tony (talk) 09:05, 18 February 2011 (UTC)
Well I do intend to keep working on this, removing the contentious suggestions and expanding it, but I am puzzled who this "us" is. And what do you mean by "I will remove the text now"? Colin°Talk 09:33, 18 February 2011 (UTC)

In support of restoring this page as a guideline, we have:

  • Colin.
  • SandyGeorgia [2]
  • WhatAmIDoing [3]
  • TCO [4]
  • Carl [5]
  • GeometryGuy [6] (though I'd class that as weak support, agreeing with Carl above)
  • Masem [7]

In opposition to restoring this page as a guideline (yet):

Colin°Talk 09:33, 18 February 2011 (UTC)

Tony, there's no "make it a MoS page" going on here. It was a MoS page for five years till you "march[ed] headlong in" and "jump[ed] the gun" (to use your language) last April. You were resisted then (but nobody was brave enough to stand up to you and revert your wrongful edit) and it is just happening again (that nobody wants to edit war against you). The consensus is actually that it should never have been demoted from that position. This just stinks of WP:OWNership. Why don't you have a think about that. Colin°Talk 10:45, 18 February 2011 (UTC)
You certainly do nurse this grudge, don't you. I thought most of this page was and still is crap, and I took out of it what little useful advice there was and put it where editors will actually find it. That is what I'm going to remove from MoS main page now, since you have decided on a policy of maximising the sprawl and minimising utility for editors. Tony (talk) 15:31, 18 February 2011 (UTC)
I'm trying to stay out of this since the page is developing quite nicely and Colin is adept at developing guideline pages, but Tony, I urge you to back off on the "grudge" allegations and avoid continued personalization of issues on this page. Since this now seems to be impacting our work here, and your view on what impacted our friendship is quite different than mine, it may be time to explore that issue on user talk pages. But not if you're not ready to avoid exploding at friends and berating them simply because they may occassionaly disagree with you; if you're prepared to interact with me without doing that yet again on user talk, I'm willing. SandyGeorgia (Talk) 15:55, 18 February 2011 (UTC)
I resent "grudge" point. And please don't reword my clunky grammar so that you change the meaning. There's no "making this a guideline" going on here. We're just restoring what should never have changed. Please accept that some people regard the nutshell and advice on this page as important enough to warrant its own guideline, not just a few lines at the bottom of the MoS page. The "where editors will actually find it" comment is quite funny. I wish also you'd stop saying "I'm going to remove from MoS main page now" and then don't. Could you just make up your mind. I would appreciate, if you do remove it from MoS, that you would either restore the guideline status here, or indicate that you aren't going to immediately revert someone else doing so. Colin°Talk 16:43, 18 February 2011 (UTC)

Adding examples

One suggestion as we clean up this page is to add before/after examples of leads or sections we feel meet the spirit of this guideline. For example, if the rhodocene article is being improved, that lead would be a prime example to include (linking back to the appropriate diffs) to help get the spirit of this across. --MASEM (t) 16:34, 16 February 2011 (UTC)

Please drop rhodocene. Too touchy. Colin°Talk 16:47, 16 February 2011 (UTC)
Why? If it is corrected, it seems like the best example to use. Certainly there are others too, but given that was the one that started this whole discussion... --MASEM (t) 16:51, 16 February 2011 (UTC)
The editor of that article has asked us to. Colin°Talk 16:52, 16 February 2011 (UTC)
The editor? Last I checked, articles were open to be edited by all. Kansan (talk) 18:17, 18 February 2011 (UTC)

Exterior algebra

There has been a lot of work on the first paragraph of exterior algebra. The lede there is long because the article ought to be split into two parts; the first two paragraphs would be a reasonable lede for one half of the article. — Carl (CBM · talk) 16:59, 16 February 2011 (UTC)

I want to comment on the lead at Exterior algebra, because the improvements there were partly due to me fussing about it, and it has been improved to the point that I'm fairly enthusiastic about it.
I won't even pretend to really understand the subject. I understand that most graduate students in mathematics don't pretend to really understand the subject. However, the lead contains information that lets me get a glimpse of the subject, and to understand why anyone cares. It was written with the notion that a university student who has had a year or two of mathematics should be able to understand the lead. I suspect that most of the rest is aimed at a student who has begun studying abstract algebra (or is about to).
A dogged pre-calculus student—the median 17-year-old student, headed for a middling university and planning to major in something other than mathematics—probably could get about this much out of the last two paragraphs in the lead:

The subject of the article (also known as something else, after some man who was probably a mathematician) is the algebraic system whose product (mathematics) is whatever the first paragraph was about. It provides an algebraic setting in which to answer geometric questions according to a set of unambiguous rules. It contains objects that are bigger or better than these blade things, which are simple. The rank of any element is defined to be something or another. The thing in the first paragraph extends to the full subject of the article, so that multiplying makes sense. Equipped with the thing in the first paragraph, the subject of the article is an associative algebra, which means something. The parts of the algebra that are sums of those blade things are called the degree k-elements (I can remember that name), and when bits of different degrees are multiplied, the degrees add (like multiplication of polynomials (which I actually know how to do)). This means that the exterior algebra is a graded algebra (I can remember that name, too).
In a precise sense (given by what is known as a universal construction (I can remember that name)), the subject of this article is the largest algebra that supports an alternating product on vectors, and can be easily defined in terms of other known objects. The definition makes sense for spaces not just of geometric vectors, but of other vector-like objects such as vector fields or functions. In full generality, it can be defined for modules over a commutative thing ("Right! Because addition is commutative!") and for other structures of interest in abstract algebra. It is one of these more general constructions where the exterior algebra finds one if its most important applications, where it appears as the algebra of something that is fundamental in areas that use some related kind of geometry. These related forms are mathematical objects that represent infinitesimal (Cool!) areas of infinitesimal parallelograms (and stuff like that), and so can be integrated over surfaces and stuff like that in a way that generalizes the lines* from calculus. The exterior algebra also has many algebraic properties that make it a convenient tool in algebra itself. The association of the exterior algebra to a vector space is a type of something on vector spaces, which means that it is compatible in a certain way with some of these things we've been talking about. The exterior algebra is one example of a bialgebra, meaning that has things and is compatible with things. This dual algebra is precisely the algebra of something, and the pairing between the exterior algebra and its dual is given by something else.

Now I realize that this butchery of the lead might induce despair in its authors, but I have a few points to make:
  • Even though this level of understanding is noticeably incomplete throughout and wrong in at least one place (at the asterisk, it should be line intergrals, not lines), it contains relevant mathematical concepts that a median 17-year-old student has heard of (all the blue links). Given that this is graduate-level mathematics, making even this much intelligible to a high-school student is an achievement that should be celebrated and encouraged.
  • When understanding <random concept> isn't really important, it directly tells the reader that this is just a name, and you don't need to worry about it. This takes the interaction from discouraging "further proof that you don't know anything" to a very encouraging "now you know more than you did five minutes ago".
  • It uses plain old English words to signal importance (all the underlined stuff): Exterior algebra answers questions. It makes sense. It has important applications. It's a convenient tool. It's compatible with stuff. It's the largest. Even if you didn't really understand mathematics beyond the fractions-and-decimals level, you'd probably get this much out of it, if you just doggedly read every word out loud and ignored whatever you'd never heard of before:

Exterior algebra answers geometric questions according to a set of unambiguous rules. It contains objects and is defined. Multiplying it makes sense. It's an algebra that you can multiply and add. In a precise sense, it's the largest algebra that supports things, and it can be easily defined in terms of other known objects. The definition makes sense for things of interest. It has important applications that are fundamental to geometry. It involves mathematical objects that represent infinite areas of infinite things and deals with surfaces and lines. The exterior algebra also has many properties that make it a convenient tool that is compatible. It's an example that is precisely compatible.

That is certainly an incomplete and inelegant reading, and some general readers may even be thinking in terms of software compatibility and technical support, but it still gives them a little taste of why anyone cares, even if they didn't understand any of the mathematics. I think that one reason this works is because we violated the adage, and just told them it was important, rather than showing them its importance. "Show, don't tell" assumes that real comprehension is available to your reader, and in this case, comprehension for everyone isn't achievable. The English parts of the lead do a little sales job for higher mathematics: Here there be dragons, sure, but you should know that some of those dragons are useful, important, convenient, or cool.
I don't know how to incorporate these concepts into the guideline, but I do think that this illustrates certain goals for "unavoidably technical" subjects. WhatamIdoing (talk) 04:25, 17 February 2011 (UTC)

My advice for that lead:

1. Use an extra paragraph break. (You are allowed four paras.)

2. cut lenght by 30-50% (yes this will involve cutting content, but it will still be in the article...if you are losing the educated reader in the lead, and I have a Ph.D. in the hard sciences and that lead makes me want to move on), then the extra length is not helping you anyhow

3. Would have to look in article, but a common problem I see with leads is a tendancy to lift a bunch of topic sentences from the body and make a poor essay that is a wikiglom of sentences. NOT saying this happened, just would check it. See if organizing the content in a different order and with different organizing principles to make paras will help make a better lead. (We all already do this with the first sentence anyhow.) Yes, all else being equal follow the order of the body, but if not, take the time to write a fresh executive summary, not a wikiglom.

4. There may be some topics in extreme math where it's hard to convey much as one needs the background. But we should not let hard cases make bad law and then write articles in biology or chemistry which CAN be dialled down, but we just choose not to.

P.s. and I say all this knowing that you took a strain to get shwere you are. Still more can be done. Imagine you were in the corporate world and needed to summarize this stuff for a smart, but non-mathematician CEO. It's possible to do more.TCO (talk) 05:12, 17 February 2011 (UTC)

I don't think our goal is to summarize it for a CEO. We can assume that the reader is actually interested in the subject and wants to spend some actual time on it (say 5-10 mins). If the reader is not actually interested in reading the article, that's not really our problem. We need to make sure that a reader who is interested will be able to work out what's going on. That's what I mean by "accessibility". It's possible for an article to be accessible, and also completely dry and uninteresting. We need to stick to accessibility here. — Carl (CBM · talk) 13:32, 17 February 2011 (UTC)

I use exterior algebra daily as a matter of routine, but have not contributed to the article (OK, I made one edit in 2008). I am impressed how much WhatamIdoing got out of the lead, despite problems with the article. As CBM notes, there are really two articles here, one on exterior product, and one on exterior algebra, and this issue can be seen in the lead. So, while the current lead may not be an exemplar, some of its practices may suggest useful advice. One thing that struck me was the use of memorable terminology and repetition, as this provides an anchor. However, as a word of caution, the term "blade" is only used in a niche of the mathematical community, which tends to use the adjectives "decomposable" and "simple" instead (also as nouns, especially in the plural). This is a nice illustration of the tension there is between accuracy and clarity: NOR and NPOV policies sometimes constrain the options editors have to make articles easier to read. Geometry guy 23:17, 17 February 2011 (UTC)

The lead section

"The lead section" section is weak. The linked-to WP:MOSINTRO text is stronger, better written and has good advice not covered here. Arguably this is related to "Put the most understandable parts of the article up front". The hierarchy being the lead sentence < lead paragraph < lead section < body in terms of difficulty. And the body's sections ordered (to some degree) on difficulty, with the really hard stuff at the bottom. And within each section, if it contains difficult material, then it too may benefit from a section lead (sentence, paragraph) that gives an accessible overview. I suggest we replace this section with something like "Take it easy at the start" that contains paragraphs on the lead, on the body section ordering, and on giving overviews within difficult sections. One idea (used in print) is for footnotes to contain short "of interest to specialists only" facts -- you don't get nearer the bottom than the footnotes!

Thoughts? Colin°Talk 22:35, 16 February 2011 (UTC)

Apart from making the lede more accessible, I generally disagree with making a general principle that the "easiest" parts of the article should come first. The goal of an article is to provide a comprehensive reference on the topic, and the editors of the article need to have the editorial freedom to decide how to do that. It might require covering difficult prerequisites first. For topics that have a formal definition or theorem statement, that is a key part of the article, and should not be relegated to the bottom.
It's true that, in an article on The Simpsons, academic topics like literary criticism should go below the stuff that "normal" people want. But for technical topics, the "normal" readers are more likely to have some background in the topic (once we get past the lede) and those with no background at all are the "different" ones. We have to keep in mind that the average readership for a an article on an esoteric technical topic is not the same as the average readership for a popular, well known topic. — Carl (CBM · talk) 12:51, 17 February 2011 (UTC)
That being said, I think the most important part of the section is the sentence "It is particularly important for the first section (the "lead" section, above the table of contents) to be accessible to a broad readership." I would like to see my three questions integrated somehow (they are already implicit in the questions that were already there, which I left when I edited the section.
Also, if we remove too many sections from the guideline, it won't have any content left. Accessibility in the lede is universally considered to be particularly important, so giving it a section seems reasonable. — Carl (CBM · talk) 12:55, 17 February 2011 (UTC)
I couldn't disagree more about the idea that technical topic article bodies are mainly read by knowlegable readers. Really advanced stuff like you work on maybe. But most technical subjets can be quite accessible. I do agree that editors need to have control over the order of sections, because the order may be necessary to build the detail, etc. I think the point should be made that where hard stuff can be moved about, moving it to the end is a good idea. An example in medicine is where the disease mechansism or pharmacology aspects are covered last -- these require some advanced mollecular biology and chemistry to appreciate. It would be totally off putting to have them at the start. First impressions count. If the reader can't understand the first body section, they will not realise the other sections are more approachable because they've gone. And even if the reader is knowlegable, it is standard practice when introducing any topic to start off easy. Colin°Talk 12:59, 17 February 2011 (UTC)
I don't see why editors can't deal with that on an article-by-article basis, though. A general principle that the article has to be ordered from simplest to most difficult would be too much of a limitation. If this page is meant to be a "guideline", it has to be broadly applicable to the vast majority of technical articles, and it can't suddenly decide that the way that all the articles are written is wrong. — Carl (CBM · talk) 13:02, 17 February 2011 (UTC)
Surely we can word this in a way to say that if section ordering is not important for some other editorial reason, moving the easy stuff to the front and the hard stuff to the back is a good idea. There are a lot of articles in the areas I deal with where sections can be moved about to some degree. Perhaps your experience is different. I don't think that just because it doesn't work for one article domain is a reason do completely drop some guidance that is useful elsewhere. We just need to make sure the guidance makes allowances for the exceptions. Colin°Talk 15:13, 17 February 2011 (UTC)
It's not just one topic where this advice interferes with the ability of editors to structure an article in a manner that is appropriate for what is being covered. Do you know what an instruction set architecture (or ISA) is? If you don't, then I suppose it's reasonable to say that it's technical, right? So along with all the hard stuff, it belongs at the bottom of an article. As an editor who works on articles about microprocessors, I disagree very strongly with any attempt to move this towards the bottom of a page. Why? Because this is one of the most important attributes of a microprocessor. The majority of coverage on microprocessors (excluding the ones incapable of discussing what the major attributes of a microprocessor are) put this sort of information up front, and these publications are not necessarily intended for a technical audience. It is not difficult at all to see how the situation can be the same for other topics.
Making articles accessible is more than just applying rules. What works and what doesn't is very domain-specific. I think prescribing rigid instruction in order to make technical articles more accessible is very wrong, and I am of the opinion that this guideline is prescriptive and rigid. It spends so much effort saying "must", "should", and "should not". Hardly any effort is spent asking editors to consider whether the advice can be implemented or not, let alone whether the advice is best for the situation.
I think this guideline needs to be less strongly worded. After all, this guideline is not some disguised rant about technical topics, is it? I think that this guideline needs to constantly remind everyone that there's more to good writing than "simplest as possible", and that they should understand what an article is about and why it is written the way it is, else they should seek clarification, before potentially mutilating an article. Rilak (talk) 06:20, 18 February 2011 (UTC)
Thank you for your comment.
I believe that where all else is equal, the simpler concepts should come first. However, when all things aren't equal, then we need to use judgment.
If complex concepts are fundamental—for example, you will never understand anything in this article if you don't know that how experts have split foo into "acute foo" and "chronic foo"—then these complex concepts must be introduced just before the reader needs that information, even if that means making them the first section.
If there is a logical structure for organizing the article, then we shouldn't abandon that structure purely for reasons of ordering sections by simplicity. For example, with a disease, the correct structure is not "Treatment: None" followed by "History: First described in 1842" followed by "Symptoms: Complex muscle spasms", even though this would order the sections by complexity.
I also believe that the same approach should be followed within each section. For example, if there are four equally important symptoms for a disease, then you should introduce the simpler ones first, and the more complex concepts last.
The order in which information is organized, therefore, should be the result of multiple factors: the natural progression of the material, the readers' immediate need to know, the importance of the particular material, and the complexity of the material. WhatamIdoing (talk) 18:09, 18 February 2011 (UTC)
I think we have agreement that the current wording is too absolute. WhatamIdoing's "where all things are equal" summary seems hard to argue with. The psychology is also hard to argue with. If you start easy, then there's a chance the reader will carry through (like the frog being boiled), but start with something really difficult and it will put them off. If ultimately you have to start with some difficult stuff, then you have to accept this is off-putting and live with it. Colin°Talk 18:56, 18 February 2011 (UTC)
So should the proposal be revised to say that multiple factors will have to be considered or should it be shelved? Rilak (talk) 04:00, 19 February 2011 (UTC)
Retrieved from "https://en.wikipedia.org/w/index.php?title=Wikipedia_talk:Make_technical_articles_understandable/Archive_2&oldid=1078917920"