Wikipedia:Make technical articles understandable

"WP:TECHNICAL" redirects here. Not to be confused with Wikipedia:Village pump (technical), Wikipedia:Naming conventions (technical restrictions), or Wikipedia:Requested moves/Technical requests.

Readability is extremely important for Wikipedia, If the readers cannot understand the content of an encyclopedia, then the encyclopedia is useless.

Some editors often conflate the encyclopedic style and academese. Encyclopedic style means the text is straight to the point and is easy to understood by a general audience, without needing to twist the truth or tell "lies for the children". It does not mean to write whatever that is true. That is why writing articles for Wikipedia is an extremely hard thing to do well – the writer needs to be on a balance between using too little or too many words.

Why readability is important

It is unreasonable to expect a comprehensive article on such subjects to be understandable to all readers, pedantically speaking. Some subjects naturally attract a more limited audience. Nevertheless, many subjects studied at an academically advanced level remain of interest to a wider audience, such as the Sun and Alzheimer's disease.

Making articles reader help beginner having an easy time understanding the content, while saving the mental load for professionals skimming for key facts and references. Trying to understand string theory is hard enough; why should we throw ourselves more roadblocks with unnecessary jargon?

Making technical content understandable should be made as an improvement to the article, not as dumbing down for the benefit of the less knowledgeable readers. A long-winded proof of Fermat's last theorem is unlikely to be read by either a general reader or an expert. However, a short summary of the proof may give some clarity to a general reader without reducing the article's usefulness to an expert reader.

Lead section

Further information: Wikipedia:Manual of Style (lead section) § Introductory text

A lead should not serve to be a perfect definition of a concept; a lead should be an introduction to that concept. A great lead would ignite a reader's curiosity and tempt them to read the body of paragraphs below. Therefore, it is not useful to be pedantic and adding fillers to the lead. The lead should instead give a good enough definition in the first sentence that is readable by everyone and then tries to elaborate on it for the rest of the lead.

It is best to explain the importance of a good lead section with an example. On 5 April 2021, the "Logic" article first two paragraphs look like this:

Logic (from Greek: λογική, logikḗ, 'possessed of reason, intellectual, dialectical, argumentative') is the systematic study of valid rules of inference, i.e. the relations that lead to the acceptance of one proposition (the conclusion) on the basis of a set of other propositions (premises). More broadly, logic is the analysis and appraisal of arguments. There is no universal agreement as to the exact definition and boundaries of logic (see § Rival conceptions). However, it has traditionally included the classification of arguments; the systematic exposition of the logical forms; the validity and soundness of deductive reasoning; the strength of inductive reasoning; the study of formal proofs and inference (including paradoxes and fallacies); and the study of syntax and semantics.

Feeling confused? You should be. Here's why the old lead sucks:

1. It does not get to the point. Only after skimming through the big first sentence could you find a comprehensible definition of the topic: Logic is the analysis and appraisal of arguments.
2. It only uses very long sentences. The whole lead only consist of 4 sentences.
3. It uses too much 'big' words. Those that is not very proficient in English would need to flip the dictionary many, many times.
4. It try to make a syntactically complete definition of the concept by trying to cover all the exceptions (There is no universal agreement as to the exact definition and boundaries of logic...).
5. It uses "and" not as a way to add concepts but as a way to add synonyms (analysis and appraisal, definition and boundaries, validity and soundness).

On 18 October 2023, thankfully, the lead reads much better:

Logic is the study of correct reasoning. It includes both formal and informal logic. Formal logic is the science of deductively valid inferences or logical truths. It studies how conclusions follow from premises due to the structure of arguments alone, independent of their topic and content. Informal logic is associated with informal fallacies, critical thinking, and argumentation theory. It examines arguments expressed in natural language while formal logic uses formal language. When used as a countable noun, the term "a logic" refers to a logical formal system that articulates a proof system. Logic plays a central role in many fields, such as philosophy, mathematics, computer science, and linguistics.

Let's see how the new lead tackles these problems:

1. It has a very easy to understand definition right at the first sentence: Logic is the study of correct reasoning. Also, the new lead got rid of the long etymology.
2. It uses a mix of short and long sentences. The short sentences serve as "breathing grounds" for readers to digest information and the long sentences serve as an elaboration of two concepts: informal and formal logic.
3. It uses simple words whenever it is possible.
4. It focus on describing the two concepts of logic and really digs down on it. (Formal logic is..., Informal logic is...) Focus on defining the topic, not on the possible exceptions of the definition.
5. It uses and to connect distinct concepts (formal and informal logic, informal fallacies, critical thinking, and argumentation theory). Bonus points for listing concrete examples.

Brainstorming tips

At the very least, the lead should provide an understandable overview of the article. It should not assume that the reader is well acquainted with the subject of the article. The lead of an article titled "Derivative" should tell a general reader:

• the field of study of the topic – calculus
• the place the topic holds in its field of study – an important tool for mathematical analysis and other fields of study
• what are the general (and hopefully interesting) facts about the topic – how to find a derivative of a function, etc.
• what needs to be learned first in order to understand the article – limits and functions

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. Linking should not be a substitute for an explanation of the main topic. However, for highly specialized topics such as string theory, it may be reasonable to cut some slack and link to the prerequisites required to understand it.

When writing the lead, ask yourself repeatingly: "So what? Why should the reader care about this?". When you get to the point where you felt you cannot answer any further, it is likely that you have reached a better way of describing what are you trying to write. This is an overly descriptive example, of course you wouldn't need to brainstorm this way. But hopefully, it will show just how powerful it is to ask yourself this question:

• There is no universal agreement as to the exact definition and boundaries of logic. (old lead)
• So what? Why should the reader care about this?
• The definition of logic is very controversial.
• So what? Why should the reader care about this?
• Because logic is complicated. There is so many topics in logic. Logical forms, deductive reasoning, inductive reasoning, inference...
• So what? Why should the reader care about this?
• They shouldn't care about all of them of course. It might be better to group these topics. Most concepts are all under formal logic, informal logic, and... that's it I think?
• So what? Why should the reader care about this?
• Because these two groups are fundamental to define what logic is. (new lead)

Rules of thumb

Reduce redundancy

Highly recommended: User:Tony1/Redundancy exercises: removing fluff from your writing

Words should be used frugally.

Put the least obscure parts of the article up front

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.

Write one level down

A general technique for increasing accessibility is to consider the typical level where the topic is studied (for example, secondary, undergraduate, or 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 more 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, from the Latin verbum meaning word, is a word (part of speech) that in syntax 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 no original research that other content is subject to.

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

Further information: Wikipedia:Graphs

Visual depictions enable many people to learn more effectively, and allow technical concepts to be communicated in a more concise and clear manner. Diagrams should be related to symbolic or verbal descriptions where appropriate. Some templates that might be useful:

• {{Location map}}: to overlay one image-symbol + label onto a map/image;
• {{Location map many}}: to overlay many image-symbols + labels onto a map/image (up to 9 markers);
• Module:Location map/data/100x100: has examples for any image as a 100-by-100 overlay grid;
• {{Superimpose}}: to overlay onto an unbordered image, such as open diagrams.

Avoid overly technical language

Main guideline: 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 (as long as accuracy is not sacrificed).
• If no precision is lost, use common terms instead of technical terms. Substitute technical terms with common terms where they are completely equivalent.
• 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.
• Eliminate long strings of adjectives, particularly technical adjectives.
• 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.
• 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, Wikipedia is not a textbook, so analogies need to be written in an encyclopedic way and be attributable to reliable sources. Extensive explanations without a specific source may constitute original research, or original research by synthesis.

Don't oversimplify

It is important not to oversimplify material in the effort to make it more understandable. Encyclopedia articles should not "tell lies to children" in the sense of giving readers an easy path to the feeling that they understand something when they don't.

Labeling articles that are too technical

Various templates are available for labeling articles that do not meet agreed standards of understandability.

For articles that are not sufficiently understandable, the {{Technical}} template should be inserted at the top of the corresponding discussion page. 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.

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

• Wikipedia:Manual of Style/Accessibility
• Wikipedia:US government technical terms
• Wikipedia:List of Introductory Articles
• Wikipedia:Writing better articles
• Wikipedia:Many things to many people
• Wikipedia:WikiProject Anatomy/Simplifying anatomical terminology
• Wikipedia:WikiProject Mathematics/Proofs
• Meta:Reading level
• Template:Technical
• Template:Over explained
• The 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

• "Topic: Writing for the Web". Nielsen Norman Group.
  • Jakob Nielsen (October 1, 1997). "How Users Read on the Web".
  • Hoa Loranger and Kate Meyer (April 23, 2017). "Writing Digital Copy for Domain Experts".
  • Hoa Loranger (October 8, 2017). "Plain Language Is for Everyone, Even Experts".
• "15–Writing Web Content". Research-Based Web Design & Usability Guidelines (PDF). U.S. Department of Health & Human Services. August 15, 2006. ISBN 0-16-076270-7.
• "Plain Language Action and Information Network". U.S. Federal Government.
• "Guidelines for preparing patient education handouts". Center for Professional Practice of Nursing. UC Davis. Archived from the original on 2013-12-07.