Wikipedia:Make technical articles understandable: Difference between revisions

Revision as of 16:50, 15 August 2025

Latest revision as of 19:25, 19 August 2025

(5 intermediate revisions by 4 users not shown)

Line 37:

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.

=== "Introduction to..." articles ===

For topics which are unavoidably technical but, at the same time, of significant interest to non-technical readers, one solution may be a separate introductory article. An example is [[Introduction to viruses]]. A complete list of current "Introduction to..." articles can be found in [[:Category:Introductory articles]], while a list of main articles thus supplemented is [[:Category:Articles with separate introductions]].

In keeping with the spirit of Wikipedia's [[WP:NOT]] policy, [[WP:LEAD]] guideline, and guideline on [[Wikipedia:Content forking|content forking]], the number of separate introductory articles should be kept to a minimum. Before you start one, ask yourself

*Following the advice given in the preceding sections, can the article be made sufficiently understandable as a whole, without the need for a separate introduction?

*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".

== Avoid overly technical language ==

''Main guideline: [[{{main|Wikipedia:Manual of Style#Technical language|Technical language]] in [[Wikipedia:Manual of Style]]''}}

* '''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.

Line 56 ⟶ 48:

* '''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]].

==<span id="The lead section">Structure</span>==

=== Lead section ===

Line 84 ⟶ 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 ===

* '''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]].

=== Explain formulae in English ===

Line 103 ⟶ 97:

* {{tlx|Location map}}: to overlay a marker + label onto a map/image;

* {{tlx|Superimpose}}: to overlay onto an unbordered image, such as open diagrams.

=== "Introduction to..." articles ===

For topics which are unavoidably technical but, at the same time, of significant interest to non-technical readers, one solution may be a separate introductory article. An example is [[Introduction to viruses]]. A complete list of current "Introduction to..." articles can be found in [[:Category:Introductory articles]], while a list of main articles thus supplemented is [[:Category:Articles with separate introductions]].

In keeping with the spirit of Wikipedia's [[WP:NOT]] policy, [[WP:LEAD]] guideline, and guideline on [[Wikipedia:Content forking|content forking]], the number of separate introductory articles should be kept to a minimum. Before you start one, ask yourself

*Following the advice given in the preceding sections, can the article be made sufficiently understandable as a whole, without the need for a separate introduction?

*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==