User:Ramzuiv/Technical Content for Everybody

These are rules of thumb I'd like to follow as I strive to make technical content more accessible while maintaining accuracy.

Good structure edit

There are at least two audiences who should be able to find value in every article: 1) a layman who likely is unfamiliar with jargon, lacks familiarity with common models understood by people educated in the topic, but is motivated to learn about the topic. 2) The expert who uses the article as a reminder about specifics regarding the topic, but has a high level of understanding of the jargon and the overall model.

After reading the introduction (that is, before they get to the table of contents), a reader should be able to explain what something is, they should be able to create a clumsy but intuitively correct replication of the article's topic, and explain why it is useful. Except in extreme cases, technical notation and jargon should be avoided in the introduction, or explained thoroughly at the very least.

Deeper in the article, experienced readers will expect in-depth technical discussion of the topic, and may find it frustrating to have every detail explained for the lay reader. However, the article should be presented in an order and with sufficient explanation to keep the lay reader from feeling completely lost, even if it's not possible or inconvenient to provide detailed explanation that provides a full picture.

Regarding links, there are so many links provided to a reader, that it can be hard for a lay reader to understand what to read first. If sufficiently detailed explanation is not feasible in-line, links to recommended reading elsewhere on Wikipedia should be brought to the users attention, so the user knows where to begin to develop a good intuition for the relevant topic.