Wikipedia

Wikipedia:Make technical articles understandable/Workshop

< Wikipedia:Make technical articles understandable

Workshop for the 2025 rewrite of WP:MTAU. This workshop will try to identify gaps in the guideline, structure it better, and give more MOS-like concrete examples on how to improve understandability for layfolks and advanced students alike.


Wikipedia guidelines
Behavioral
Discussions
Content
Editing
Categorization
Style
Deletion
Project content
Other
Search

Wikipedia articles should be written for the widest possible general audience.

As a free encyclopedia, Wikipedia serves readers with widely varying backgrounds, interests, and goals. Even in articles on the most complex subjects, the audience includes not only experts, but also students, professionals from other fields, and curious laypeople. Information that is clear and easy to follow benefits all of them.

While comprehensive coverage remains a central goal, every effort should be made to also make articles accessible and pleasant to read for less-prepared readers. The lead section should use plain language and present the topic in a way that draws in a broad readership. For the body of the article, a common strategy is to begin with broadly understandable aspects of the subject before moving to more advanced or specialised material. Well-designed images can greatly help understanding too.

Wikipedia's style is encyclopaedic, not academic. Articles should avoid oversimplifications, but also minimise jargon, and not take prior knowledge for granted. They should be largely self-contained, offering essential explanations within the text rather than relying heavily on links. Since it is often hard to know what others do not understand, collaboration among editors with different levels of expertise can be very helpful.


Audience

edit
Shortcut
See also: WP:Writing better articles § Audience

Wikipedia has a varied audience, which can be grouped in three ways:

  • On familiarity with the subject.
    • The general reader 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 further detail or a quick reminder of a fact
  • On reading ability.
  • By motivation to learn about the topic.
'Option A'

In general on Wikipedia, around 40% of readers say they are unfamiliar with the topic they are reading. Around 25% of readers are looking for in-depth knowledge, while others may be interested in a fact or an overview of the topic. Over a third of readers speaks English as a second language.

Most Wikipedia articles can be written for a general reader with average reading ability and motivation. This includes most technical articles. For subjects that are inherently complex or require specialised knowledge, a fully accessible article may be unrealistic, but they should be made as clear as possible, especially in the lead section. Some topics naturally draw a narrower audience, for example those requiring years of specialist study in advanced mathematics, specialist law, or industrial engineering. These audiences benefit from clear explanations, effective visuals, and plain English, but need less background detail or definitions of jargon. Other advanced topics, like the Sun or Alzheimer’s disease, remain of broad public interest, and should be written with this audience in mind.

'Option B' (closer to original)

A well-written article will grab the interest of all these groups and let them learn as much as they are able and motivated to do. An article may disappoint because it is written well above the reading ability of the reader, because it wrongly assumes certain background knowledge, or because it covers the topic at too basic a level and is not comprehensive. Although different audiences have different needs, clear and understandable writing benefits readers across the board.

Some subjects naturally attract a more limited audience, especially those that require years of specialist study. For example, a topic in advanced mathematics, specialist law, or industrial engineering may contain material that only knowledgeable readers can appreciate or even understand. Other highly complex topics, though, attract a wider audience. For example, the Sun is of interest to more than just astronomers, and Alzheimer's disease will interest more than just physicians.

Most Wikipedia articles can be written to be fully understandable to the general reader with average reading ability and motivation. Some articles are technical in nature and some have technical sections or aspects. Many of these can still be written to be understandable to a wide audience. Other topics are intrinsically complex or demand substantial prior knowledge. 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

edit
Shortcut

For articles not of broad public interest, write "one level down" to increase understandability. 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 understandability. 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

edit
Shortcut

Wikipedia aims to be a serious reference, and highly technical content rightly belongs in some articles. The goal is to make such material accessible to less knowledgeable readers while maintaining its value and clarity for experts. For example, an article on a chemical compound should include its properties, even if some are obscure to general readers. Summarising complex details often enhances readability for all audiences, including experts. For instance, a lengthy mathematical proof may discourage both general readers and experts, but a clear summary can benefit everyone.

When deciding how much technical detail to include, consulting standard reference works in the field can provide useful guidance. However, sources like scientific papers are often written for specialists and may assume more background knowledge than the Wikipedia audience for the topic. Textbooks can be useful for identifying ways to explain complex concepts more clearly to a broader audience.

Use clear language

edit

Limit technical language

edit

See also: Technical language in Wikipedia:Manual of Style

To make Wikipedia articles accessible to the widest possible audience, avoid overly technical language. There are several ways to handle jargon—the best strategy is often to replace it with plain English, but for more technical articles you can provide brief explanations, or sometimes provide a wikilink.

Overexplained jargon can make an article less engaging, so consider whether the jargon can be avoided altogether. Do not introduce technical terms just for the sake of teaching them.

  1. Avoid jargon by replacing it with plain English alternatives, if there is minimal loss of precision. For instance, avoid Latin synonyms for species or anatomical concepts, except in their own article. Write House sparrow instead of House sparrow (Passer domesticus) or Passer domesticus. Often, one can replace a jargon term directly with the explanation, and link the entire explanation to the respective article. E.g., It is known from experience that … instead of A posteriori …
  2. Use plain English and add jargon between brackets once. This option may work if some precision is lost, but the plain English synonym works well enough for the context. The goal of the jargon is to clarify to experts what you mean exactly. The drug reduces the risk of a heart attack (myocardial infarction). Consider whether wikilinking to the precise article is sufficient.
  3. Use the jargon and explain between brackets. This might be useful when the explanation is quite wordy and you want to reuse the jargon afterwards. Do not introduce too much jargon like this, as it rapidly becomes challenging to remember many new terms. This can be appropriate when you expect many readers to already be familiar with the jargon or if the jargon is essential for the rest of the article. Note that readers do not always read the article linearly.
  4. Use implicit explanations or definitions. For instance, the sentence The archaeologists used stratigraphy to determine which artefacts were oldest. implies that stratigraphy is a dating method. This kind of contextual clue can help readers recall the meaning of a term introduced earlier, without repeating the full definition.
  5. Only rely on wikilinks on their own when you expect most of your readers to already be familiar with the term

Use the most familiar form of jargon wherever possible. For instance, write emissions from vehicles rather than vehicular emissions. Expand abbreviations when they are first used, and repeat as necessary in further sections. Avoid elegant variation with technical terms: using different words to refer to the same concept can create ambiguity. Avoid scientific notation that is unfamiliar to many readers: Dodson (1998) argued that ⇒ In 1998, Dodson argued that.

Words with different meanings for experts and non-experts

edit

Some words have a different meaning for experts than for non-experts. For example, an uncertainty interval indicates how confident scientists are in a certain finding, but may imply the opposite to readers.

Words can have different meanings to different audiences
Word Expert meaning Normal meaning
Theory Current understanding based on evidence Hunch, something unproven
Significant Statistically unlikely to have happened by chance Important
Error Difference between measurement and true value A mistake
Bias A systemic deviation from the true value Prejudice
Model A mathematical or cognitive model of some aspect of reality A physical thing, such as a model train

Use plain English

edit

Communicating technical content in plain English benefits everyone, from experts to novices. It ensures readers can focus on the material without being distracted by complex language. Many Wikipedia readers speak English as a second language and may be unfamiliar with more idiomatic language (phrases that do not translate literally). People can only hold a few chunks of information in their working memory, so avoid overloading them in complicated sentences. A few tips for writing clearly:

  • Use simpler synonyms. Replace utilise with use, comprise with consist of, commence with start, terminate with end, and prior to with before.
  • Use short sentences, paragraphs and sections. Only using short sentences impedes flow, which makes it more challenging to read, so vary with medium-length sentences. Understanding starts to drop when sentence lengths exceed 15 words.[a][1]
  • Avoid redundancy to keep sentences to the point.
  • Use active voice rather than passive voice, especially when it is more concise.
  • Put important information at the start and end, and do not delay your main verb. Replace Effective education policies, by providing better resources and training for teachers, improve student outcomes. with Effective education policies improve student outcomes by providing better resources and training for teachers.
  • Be concrete, for instance say Rules that limit factory emissions help reduce pollution. instead of Environmental policies aim to reduce pollution. Avoid overuse of 'former' and 'latter', as readers have to go back to the previous sentence.
  • Use bullet points where appropriate. Use bullet point to split up long sentences, but avoid paragraph-length bullet points.

Structure articles well

edit

When organising content, it is important to use a clear and logical structure that guides the reader through the material smoothly. This helps improve understanding and keeps the article accessible. Additionally, section headings should avoid jargon or specialised terms to ensure they are easily understood by a wide audience. For instance, use Reproduction for a section header, rather than Phenology, or Mechanism instead of Pathophysiology. Clear, simple headings make it easier for readers to navigate the article and find the information they need.

Lead section

edit
Further information: Wikipedia:Manual of Style (lead section) § Provide an accessible overview
Shortcut

It is particularly important for the 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 are unfamiliar with the topic. 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.

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 and caveats in the body of the article. Do not try to put all formal details in the first sentence and avoid lead clutter such as pronunciation. 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. Keep the lead concise; for reference, the lead for a typical Featured Article is about 300 words.

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

Put easier content up front

edit
Shortcut

It's perfectly fine for later parts of articles 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. This is true both within the article, and within sections, as readers may jump to the middle of the article from the table of contents. Keep the start of a section understandable especially if it is the target of a redirect.

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.

Explain new concepts

edit

When explaining a complex concept, it can often be helpful to start with an approximate explanation. When a less complete or precise explanation is given, preface it with a phrase such as "Generally..." or "With some exceptions...", or start the following sentence with "More precisely" or "More formally", 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. For example, the mathematical concept of the Klein bottle is first explained in everyday terms, before a formal definition is given.

A background section may make it easier for people new to the topic to learn complex issues. A good example of a background section can be found in Special relativity § Background. If possible, give the section a more specific name such as 'Terminology'.

Examples

edit

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 no original research that other content is subject to.

Analogies and comparisons

edit

Sometimes it is useful to 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.

For example, the article on DNA uses the analogy that:

The two strands of DNA in a double helix can be pulled apart like a zipper.

Similarly, comparisons help provide context, especially size comparisons. For instance, the article on particulate matter compares these pollutants to the thickness of a human hair.

Explain formulas in English

edit

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.

Don't oversimplify

edit
Shortcut

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.

Use of visuals

edit
Further information: Wikipedia:Graphics Lab

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 designing images or writing captions, keep in mind that readers may look at figures and captions before the surrounding text. As such, minimise abbreviations and jargon, and avoid cluttering graphs and diagrams with unnecessary detail and decoration. Use accessible color combinations and make sure embedded text is readable at the intended image size.

For simple data visualisation (bar chart, line chart, etc.), you can use Wikipedia templates and extensions. For more complicated graphs, use external software.

Seeking feedback

edit
Shortcut

When people learn about a topic, they start overestimating how much others know about it. This effect, known as the curse of knowledge, may lead them to overuse jargon or assume too much background knowledge from their readers. The cognitive bias is difficult to counter: simply knowing about it, or imagining a less knowledgeable audience, does not reduce how much people overestimate their readers.

Given this, seeking feedback from others is key. As the understandability guideline is part of the GA criteria, that is one avenue for feedback on understandability. Wikiprojects and Wikipedia's peer review process are another. Finally, consider asking friends and family to sense-check parts of the article, if they are part of the expected audience of the article you are working on.

See also

edit

References and notes

edit
  1. ^ A study by the American Press Institute found that people fully understand 8-word sentences, understand 90% of 15-word sentences, 50% of 28-word sentences and 10% of 43-word sentences.
  1. ^ Dennis, Meredith (2021). Explaining Research: How to Reach Key Audiences to Advance Your Network. Oxford University Press. p. 85. ISBN 9780197571347.
Retrieved from "https://en.wikipedia.org/w/index.php?title=Wikipedia:Make_technical_articles_understandable/Workshop&oldid=1308585782"