Content quality

How well MDS documentation is rated today.

Each component package is reviewed on the descriptions of its props, events and slots, against four lenses: Clarity, Completeness, Accuracy and Consistency. Accuracy checks a description against the package’s types, defaults and options. Consistency checks that shared words such as disabled or size read the same across components. Read more about the MDS Authoring Kit for how we rate and maintain API descriptions.

Estate reviews

Component breakdown

How to read the dashboard

Each package gets an overall Quality (High, Medium or Low) and a rating for each lens:

  • Strong
  • Mixed
  • Weak

The four lenses each ask one question:

  • Clarity: Is the wording easy to understand? This is about what the description says. A description that only repeats the name, or is a confusing fragment, is unclear.
  • Completeness: Does the description include everything you need to use it? This is about what is missing. A description can be easy to read and still leave out which values it takes, what an event sends, or when it applies.
  • Accuracy: Is the description correct? This is about a single description against the details listed with it. A description is inaccurate if it names a value, default or option that the type, default and options don’t support.
  • Consistency: Is the same thing described the same way everywhere? This is about comparing components with each other. Each description can be clear and accurate on its own, yet disabled or size may be explained in ways that don’t match from one component to the next.

A description that several packages share is reviewed once, and a finding on it applies to every package that uses it. A shared description lowers a package by at most one step.

Select a review to see which packages it rated, or a component to see every rating it has had, the reason for each and a link to the full review.

A rating is a guide to where descriptions can improve. It is a worklist, not an audit: a component is never blocked from release because of its rating. The review does not find every issue, and the number of issues it finds varies between runs, so a clean rating is not proof that nothing is wrong.

See also