Wikipedia:Make technical articles understandable

"WP:TECHNICAL" redirects here. For technical questions and proposals, see Wikipedia:Village pump (technical). For technical restrictions on article titles, see Wikipedia:Naming conventions (technical restrictions).

Wikipedia guidelines
Guidelines list Policies list
Behavioral
Assume good faith Conflict of interest Courtesy vanishing Disruptive editing Don't bite the newbies Don't edit to make a point Etiquette Don't game the system User pages Other behavioral guidelines WMF friendly space policy Discussions Talk page guidelines Signatures
Content
Citing sources External links Reliable sources medicine Fringe theories Non-free content Offensive material Don't copy long texts Don't create hoaxes Patent nonsense Portal namespace Other content guidelines
Editing
Article size Be bold Edit summary Understandability Other editing guidelines Organization Categories, lists, templates Categorization Disambiguation
Style
Manual of Style contents lists tables
Deletion
Deletion process Speedy keep Deletion guidelines for administrators
Project content
Project pages WikiProjects Templates User pages User boxes Shortcuts Subpages
Other
Naming conventions Notability

The content in articles in Wikipedia should be written as far as possible for the widest possible general audience.

When adding content and creating new articles, an encyclopedic style with a formal tone is important. Instead of essay-like, argumentative, or opinionated writing, Wikipedia articles should have a straightforward, just-the-facts style. Every reasonable attempt should be made to ensure that material is presented in the most widely understandable manner possible. If an article is written in a highly technical manner, but the material permits a more understandable explanation, then editors are strongly encouraged to rewrite it.

Audience

Wikipedia has a varied audience who can be graded in three ways:

• On familiarity with the subject.
  • The general reader has no advanced education in the topic's field, 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 to learn more or be reminded about some fact, or is curious about Wikipedia's coverage.
• On reading ability. Various free online tools can automatically grade the readability of text or highlight complex sentence structures, like http://www.hemingwayapp.com or http://www.readabilityofwikipedia.com
• By motivation to learn about the topic.

A highly educated, knowledgeable and motivated reader may comfortably read a 5000-word featured article to the end. Another reader may struggle through the lead and look at the pictures. A good article will grab the interest of all readers and allow them to learn as much about the subject 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 the reader is familiar with the subject or field, or because it covers the topic to too basic a level or is not comprehensive.

While a member of any of the audience groups may stumble upon an article and decide to read it (for example, by clicking on Special:Random), some subjects naturally attract a more limited audience. A topic that requires many years of specialist education or training prior to being studied or discussed is in general likely to have a more limited audience. For example, a topic in advanced mathematics, specialist law or industrial engineering may contain material that only knowledgeable readers can appreciate or even understand. On the other hand many subjects studied at an academically advanced level remain of interest to 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 by the general reader with average reading ability and motivation. Some articles are themselves technical in nature and some articles have technical sections or aspects. Many of these can still be written to be understandable to a wide audience. Some topics are intrinsically complex or require much prior knowledge gained through specialized education or training. 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.

Technical content

Wikipedia strives to be a serious reference resource, and highly technical subject matter still belongs in some Wikipedia articles. Increasing the understandability of technical content is intended to be an improvement to the article for the benefit of the less knowledgeable readers, but this should be done without reducing the value to readers with more technical background.

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. But often summarizing highly technical details can improve the readability of the text for general readers and experts alike. For example, a detailed derivation of a result is unlikely to be read by either a general reader or an expert, but a short summary of the derivation may convey a sense to a general reader without reducing the usefulness to an expert reader. When trying to decide what amount of technical detail is appropriate to include, it may be helpful to compare with a standard reference work in the particular technical field to which the subject of the article belongs.

Lead section

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

It is particularly important for the first section (the "lead" section, above the table of contents) 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 don't already know the topic in detail. 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.

For these reasons, the lead should provide an understandable overview 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 in the lead, and including the technical details in the body of the article. 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.

In general, the lead should not assume that the reader is well-acquainted with the subject of the article. For highly specialised 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.

Rules of thumb

Here are some more ideas for dealing with moderately or highly technical subjects:

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 should also be understandable. Further, even more-technical sections can often be improved upon by summarizing the main ideas in their first paragraph, before going into details.

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.
• 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".
• Trenton Moss (1 August 2005). "Content & usability: Web writing". Webcredible.
• "15". Writing Web Content (PDF). Research-Based Web Design & Usability Guidelines. 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.
• "Plain Talk". CommunityWiki.
• "Albert Einstein's Theory of Relativity: In Words of Four Letters or Less". MuppetLabs.