Wikipedia:Make technical articles understandable: Difference between revisions
Content deleted Content added
→Add a concrete example: simplified here as well as in article. Etymology is not needed to understand the topic of the article |
move introduction to pages down again (to be discussed in separate RfC question) |
||
| (31 intermediate revisions by 9 users not shown) | |||
Line 1:
{{short description|Wikipedia editing guideline}}
{{Redirect|WP:TECHNICAL}}
{{subcat guideline|editing guideline|Make technical|WP:MTAU|WP:TECHNICAL}}
Line 9 ⟶ 8:
As a free encyclopedia, Wikipedia serves readers with a wide range in backgrounds, interests, and goals. Even for articles about the most technically demanding subjects, these readers include students and curious laypeople in addition to experts. While upholding the goals of accuracy and full coverage of the most important aspects of a topic, every effort should be made to also make articles accessible and pleasant to read for less-prepared readers. It is especially important to make the [[WP:LEAD|lead section]] understandable using plain language, and it is often helpful to begin with more common and accessible subtopics, then proceed to those requiring advanced knowledge or addressing niche specialties.
Articles should be written in encyclopedic style,
== Audience ==
{{shortcut|WP:GENAUD}}
{{See also|WP:Writing better articles#Audience}}
Wikipedia has a varied audience who can be graded in three ways:
Line 18:
** The ''general reader'' has no advanced education in the topic's field, is largely unfamiliar with the topic itself, and may even be unsure what the topic is.
** The ''knowledgeable reader'' has an education in the topic's field but wants to learn about the topic itself.
** The ''expert reader'' knows the topic but wants to learn more or be quickly reminded about some fact, or is curious about Wikipedia's coverage.
* On reading ability.
* By motivation to learn about the topic.
Line 28:
Most Wikipedia articles can be written to be fully understandable by the general reader with average reading ability and motivation. Some articles are themselves technical in nature and some articles have technical sections or aspects. Many of these can still be written to be understandable to a wide audience. Some topics are intrinsically complex or require much prior knowledge gained through specialized education or training. It is unreasonable to expect a comprehensive article on such subjects to be understandable to all readers. The effort should still be made to make the article as understandable to as many as possible, with particular emphasis on the lead section.
===Write one level down===
==Technical content==▼
{{shortcut|WP:ONEDOWN}}▼
A general technique for increasing understandability is to consider the typical level where the topic is studied (for example, [[secondary education|secondary]], [[undergraduate education|undergraduate]], or [[postgraduate education|postgraduate]]) and write the article for readers who are at the previous level. Thus articles on undergraduate topics can be aimed at a reader with a secondary school background, and articles on postgraduate topics can be aimed at readers with some undergraduate background. The lead section should be particularly understandable, but the advice to write one level down can be applied to the entire article, increasing the overall accessibility. Writing one level down also supports our goal to provide a tertiary source on the topic, which readers can use before they begin to read other sources about it.▼
▲===Technical content===
{{shortcut|WP:TECH-CONTENT}}
Wikipedia strives to be a serious reference resource, and highly technical subject matter still belongs in some Wikipedia articles. The goal is to make technical information easier to understand for less knowledgeable readers, without losing its value for experts.
Line 34 ⟶ 38:
Making articles more understandable does not necessarily mean that detailed technical content should be removed. For instance, an encyclopedia article about a chemical compound is expected to include properties of the compound, even if some of those properties are obscure to a general reader. Often, summarizing highly technical details can improve the readability of the text for general readers and experts alike. For example, a long-winded mathematical proof is unlikely to be read by either a general reader or an expert, but a short summary of the proof can inform a general reader without reducing the usefulness to an expert reader. When trying to decide how much technical detail to include, it may be helpful to compare with a standard reference work in the particular technical field.
{{
* '''Use jargon and acronyms judiciously.''' Explain technical terms and expand acronyms when they are first used. In addition, you might consider using them sparingly thereafter, or not at all. Especially if there are many new terms being introduced all at once, substituting a more familiar English word might help reduce confusion.▼
* '''If no precision is lost, use common terms instead of technical terms'''. Substitute technical terms with common terms where they are completely equivalent.▼
* '''Use less technical versions of words.''' For instance, say "emissions from vehicles", rather than "vehicular emissions". ▼
* '''Consider prefacing explanatory sentences with caveats.''' When a less complete or precise explanation is given to improve clarity, preface it with a phrase such as "Generally..." or "With some exceptions..." so the reader knows that there is more complexity behind the explanation. Follow the brief explanatory sentence(s) with more detail, or include a "robust definition" section so that the article as a whole is complete and precise. ▼
* '''Use bullet points where appropriate'''. Use bullet point to split up long sentences, but avoid paragraph-length bullet points. ▼
* '''Use some short sentences and short paragraphs.''' Comprehension decreases when average sentence length exceeds about 12 words. However, using too many short sentences in a row becomes monotonous and stilted; vary sentence length to maintain reader interest. Similarly, split long paragraphs into smaller ones.▼
* '''Use language similar to what you would use in a conversation.''' Many people use more technical language when writing articles and speaking at conferences, but try to use more understandable prose in conversation.▼
==Structure==
{{see|Wikipedia:Manual of Style (lead section)#Provide an accessible overview}}
{{shortcut|WP:EXPLAINLEAD}}
It is particularly important for the [[WP:LEAD|first section]] (the "lead" section, above the first heading) to be understandable to a broad readership. Readers need to be able to tell what an article is about and whether they are reading the correct article, even if they don't already know the topic in detail. Those who are only looking for a summary or general definition may stop reading at the end of the lead. An understandable lead encourages readers to continue reading into the body of the article.
For these reasons, the lead should provide an understandable overview of the article. While the lead is intended to mention all key aspects of the topic in some way, accessibility can be improved by only summarizing the topic in the lead and placing the technical details in the body of the article. The lead of the article should tell a general reader the field of study of the topic, the place the topic holds in its field of study, what (if anything) the topic is good for, and what needs to be learned first in order to understand the article.
In general, the lead should not assume that the reader is well acquainted with the subject of the article. Terminology in the lead section should be [[WP:JARGON|understandable on sight]] to general readers whenever this can be done in a way that still adequately summarizes the article, and should not depend on a [[WP:wikilink|link]] to another article. Any link to another article should be a supplement to provide more information, and preferably should not be required for understanding text in the lead. For highly specialized topics where it is difficult to give an overview in terms with which a general audience will be familiar, it may be reasonable to assume some background knowledge in the lead while linking to the prerequisites required to understand it. For reference, the lead for a typical [[Wikipedia:Featured articles|Featured Article]] includes about 20 links to other articles (with a mean lead length around 300 words).
Here are some more ideas for dealing with moderately or highly technical subjects:▼
===Put the easier parts of the article up front===
{{shortcut|WP:UPFRONT}}
It's perfectly fine for later sections to be more technical, if necessary. Those who are not interested in details will simply stop reading at some point, which is why the material ''they'' are interested in needs to come first. Linked sections of the article should ideally start out at a similar technical level so that if the first, easier paragraph of an article links to a section in the middle of the article, the first part of the section linked to it should also be understandable. Further, even more-technical sections can often be improved upon by summarizing the main ideas in the first paragraph before going into details.
Avoid circular explanations: don't define A in terms of B, and B in terms of A. Check to make sure that technical terms are not used ''before'' they are defined.
==
▲Here are some more ideas for dealing with moderately or highly technical subjects:
▲{{shortcut|WP:ONEDOWN}}
▲A general technique for increasing understandability is to consider the typical level where the topic is studied (for example, [[secondary education|secondary]], [[undergraduate education|undergraduate]], or [[postgraduate education|postgraduate]]) and write the article for readers who are at the previous level. Thus articles on undergraduate topics can be aimed at a reader with a secondary school background, and articles on postgraduate topics can be aimed at readers with some undergraduate background. The lead section should be particularly understandable, but the advice to write one level down can be applied to the entire article, increasing the overall accessibility. Writing one level down also supports our goal to provide a tertiary source on the topic, which readers can use before they begin to read other sources about it.
=== Add a concrete example===
Many technical articles are not understandable (and confusing even to expert readers) only because they are abstract. A concrete example can help many readers to put the abstract content in context. Sometimes a contrasting example (counterexample) can also be helpful. For instance, from the article [[verb]]:
:A '''verb''' is a [[word]] that generally conveys an action (''bring'', ''read'', ''walk'', ''run'', ''learn''), an occurrence (''happen'', ''become''), or a state of being (''be'', ''exist'', ''stand'').
Examples must still meet the same requirement of [[WP:NOR|no original research]] that other content is subject to.
=== Analogies ===
=== Explain formulae in English ===
When possible, even for experts it can be helpful to explain in English why the formula has certain features or is written a certain way. Explaining the "meaning" of a formula helps readers follow along. At a minimum, make sure all the variables in a formula are defined in the article, or have links to articles that explain them.
▲=== Add a picture ===
{{See|Wikipedia:Graphs}}▼
Images enable many people to learn more effectively, and allow technical concepts to be communicated in a more concise and clear manner. Diagrams should be clearly described and where appropriate, should be related to the text or equations. Some templates that might be useful:▼
* {{tlx|Location map}}: to overlay one marker + label onto a map/image;▼
* {{tlx|Superimpose}}: to overlay onto an unbordered image, such as open diagrams.▼
▲=== Avoid overly technical language ===
▲* '''Use jargon and acronyms judiciously.''' Explain technical terms and expand acronyms when they are first used. In addition, you might consider using them sparingly thereafter, or not at all. Especially if there are many new terms being introduced all at once, substituting a more familiar English word might help reduce confusion.
▲* '''If no precision is lost, use common terms instead of technical terms'''. Substitute technical terms with common terms where they are completely equivalent.
▲* '''Use less technical versions of words.''' For instance, say "emissions from vehicles", rather than "vehicular emissions".
▲* '''Consider prefacing explanatory sentences with caveats.''' When a less complete or precise explanation is given to improve clarity, preface it with a phrase such as "Generally..." or "With some exceptions..." so the reader knows that there is more complexity behind the explanation. Follow the brief explanatory sentence(s) with more detail, or include a "robust definition" section so that the article as a whole is complete and precise.
▲* '''Use bullet points where appropriate'''. Use bullet point to split up long sentences, but avoid paragraph-length bullet points.
▲* '''Use some short sentences and short paragraphs.''' Comprehension decreases when average sentence length exceeds about 12 words. However, using too many short sentences in a row becomes monotonous and stilted; vary sentence length to maintain reader interest. Similarly, split long paragraphs into smaller ones.
▲* '''Use language similar to what you would use in a conversation.''' Many people use more technical language when writing articles and speaking at conferences, but try to use more understandable prose in conversation.
▲* '''Use analogies''' to describe a subject in everyday terms. Avoid far-out analogies. The best analogies can make all the difference between incomprehension and full understanding. However, [[WP:NOTTEXTBOOK|Wikipedia is not a textbook]], so analogies need to be written in an encyclopedic way and be [[WP:V|attributable]] to [[WP:RS|reliable sources]]. Extensive explanations without a specific source may constitute [[WP:NOR|original research]], or [[WP:SYNTH|original research by synthesis]].
=== Don't oversimplify ===
Line 89 ⟶ 86:
It is important not to oversimplify material in the effort to make it more understandable. Encyclopedia articles should not "[[Lie-to-children|tell lies to children]]" in the sense of giving readers an easy path to the feeling that they understand something when they don't.
==
For articles that are not sufficiently understandable, the {{tlx|Technical}} template should be
▲For articles that are not sufficiently understandable, the {{tlx|Technical}} template should be inserted at the top of the article. ''You should put an explanation on the talk page with comments on why you believe it is too technical, or suggestions for improvement''. Templates added without explanation are likely to be either ignored or removed. Articles containing this template can be found in [[:Category:Wikipedia articles that are too technical]].
This tag should be used only on articles which you feel could be improved by someone following the guidelines listed above.
== Use of visuals ==
▲{{See|Wikipedia:Graphs}}
▲Images enable many people to learn more effectively, and allow technical concepts to be communicated in a more concise and clear manner. Diagrams should be clearly described and where appropriate, should be related to the text or equations. When writing figure captions, keep in mind that readers may look at figures and captions before the surrounding text. Some templates that might be useful:
▲* {{tlx|Superimpose}}: to overlay onto an unbordered image, such as open diagrams.
== "Introduction to..." articles ==
Line 103 ⟶ 105:
*Given the degree of general interest in the topic at hand, might a well-written lead be sufficient?
You may start an "Introduction to..." article if the answer to these questions is "no".
==See also==
Line 111 ⟶ 114:
* [[Wikipedia:WikiProject Mathematics/Proofs]]
* [[:Template:Technical]]
* The [[w:simple:|Simple English Wikipedia]] aims to provide full explanations using a limited subset of English. It is a resource both for examples (articles) and advice (guidelines) on using simpler language without dumbing down.
==External links==
* [https://readability.toolforge.org/ Wikimedia tool to measure the readability of Wikipedia articles]
* {{cite web |url= https://www.nngroup.com/topic/writing-web/ |title= Topic: Writing for the Web |publisher= [[Nielsen Norman Group]]}}
** {{cite web |url= https://www.nngroup.com/articles/how-users-read-on-the-web/ |title= How Users Read on the Web |date= October 1, 1997
| |||