Wikipedia:Make technical articles understandable: Difference between revisions

Revision as of 17:16, 15 August 2025

Latest revision as of 19:25, 19 August 2025

(3 intermediate revisions by 3 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 ==

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