Wikipedia:Make technical articles understandable: Difference between revisions
Content deleted Content added
move 'use of visuals' to its own section, per talk |
move introduction to pages down again (to be discussed in separate RfC question) |
||
| (8 intermediate revisions by 4 users not shown) | |||
Line 1:
{{short description|Wikipedia editing guideline}}
{{Redirect|WP:TECHNICAL}}
{{subcat guideline|editing guideline|Make technical|WP:MTAU|WP:TECHNICAL}}
Line 33 ⟶ 32:
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 39 ⟶ 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.
{{main|Wikipedia:Manual of Style#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.▼
==Structure==
=== Lead section ===
Line 58 ⟶ 68:
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:
Line 65 ⟶ 75:
: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.
▲=== 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 104 ⟶ 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==
| |||