Unclear and Contradictory Definitions of 'Viewport' in Glossary Page

[zakir0101]

MDN URL

https://developer.mozilla.org/en-US/docs/Glossary/Viewport

What specific section or headline is this issue about?

First two Paragraphs in this article

What information was incorrect, unhelpful, or incomplete?

Description:

I would like to report several issues with the current definitions on the "Viewport" glossary page. The explanations provided are unclear, contradictory, and may confuse readers, especially those new to the topic.

---

1. Vague Initial Definition Relies on Reader Interpretation

• Excerpt:

  "A viewport represents a polygonal (normally rectangular) area in computer graphics that is currently being viewed. In web browser terms..."

• Problem:
  The author acknowledges that readers might be unfamiliar with the topic, indicating a need for a clear and comprehensive definition. However, the initial explanation is vague and relies on the reader's prior knowledge or interpretation, which is unhelpful for beginners seeking to understand the concept from this resource.

---

2. Confusing Definition of 'Viewport' as the Visible Part of the Document

• Excerpt:

  "In web browser terms, it refers to the part of the document you're viewing which is currently visible in its window (or the screen, if the document is being viewed in full screen mode). Content outside the viewport is not visible onscreen until scrolled into view."

• Problem:
  The author defines 'Viewport' as the visible part of the document, emphasizing "currently visible." This suggests that the viewport is only the part of the document that's displayed on the screen at any given moment. This can be misleading because it implies that content outside this area is not part of the viewport, which contradicts other explanations where the viewport may encompass more than just the visible portion.

---

3. Contradictory Introduction of 'Visual Viewport'

• Excerpt:

  "The portion of the viewport that is currently visible is called the visual viewport. This can be smaller than the layout viewport..."

• Problem:
  Here, 'Visual Viewport' is introduced as the portion of the 'Viewport' that is currently visible. This implies that the 'Viewport' includes areas not currently visible, which contradicts the earlier definition where the 'Viewport' was described as the visible part of the document. This inconsistency creates confusion about what the 'Viewport' actually includes—whether it's only the visible area or also includes non-visible (scrollable) areas.

---

4. Introduction of 'Layout Viewport' Without Prior Explanation

• Excerpt:

  "This can be smaller than the layout viewport..."

• Problem:
  The term 'Layout Viewport' is introduced without any prior definition or explanation. For a beginner, this sudden mention adds to the confusion, as they have no context for what the 'Layout Viewport' refers to. Since it wasn't previously defined, comparing the 'Visual Viewport' to the 'Layout Viewport' lacks clarity and can further mislead the reader.

---

Summary:

The article contains inconsistencies and contradictions in its definitions:

• The 'Viewport' is first defined as the visible part of the document but later is implied to include non-visible areas.
• The 'Visual Viewport' is introduced as the visible portion of the 'Viewport', contradicting the initial definition of 'Viewport'.
• The 'Layout Viewport' is mentioned without prior definition, leaving readers unsure of its meaning and relation to the other terms.

What did you expect to see?

Suggestions for Improvement:

1. Provide Clear and Consistent Definitions:

   • Viewport:

     • Offer a precise definition that consistently explains what the 'Viewport' includes.
     • Clarify whether it refers to the entire area where the document is laid out or just the visible portion.

   • Visual Viewport:

     • Define the 'Visual Viewport' clearly and explain how it relates to the 'Viewport'.

   • Layout Viewport:

     • Introduce and define the 'Layout Viewport' before using it in any comparisons.
     • Explain its significance and how it differs from the 'Visual Viewport'.

2. Avoid Contradictions:

   • Ensure that the definitions do not contradict each other.
   • Maintain consistency in how each term is described throughout the article.

3. Introduce Terms in Logical Order:

   • Present the terms in a sequence that builds understanding.
   • Start with the most general term ('Viewport'), then introduce related concepts ('Visual Viewport', 'Layout Viewport') with clear explanations.

4. Enhance Clarity for Beginners:

   • Use straightforward language that doesn't rely on prior knowledge.
   • Consider adding examples or visual aids to illustrate the differences between the terms.

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

No response