mdn / mdn/data

Expose short descriptions for CSS properties in mdn/data

Open
#262 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Epic idle
Dominant language
JavaScript
Stars
787
Forks
216
Avg merge
1d 5h
Merged PRs (30d)
6

Description

This is to address https://github.com/mdn/data/issues/199 for CSS properties.

The overall proposal for how we are going to do this is captured in the [CSS property short descriptions](https://github.com/mdn/data/wiki/CSS-property-short-descriptions) Wiki document.

Broadly there are two aspects to the work: (1) fixing up the content and then (2) getting it into mdn/data:

## Check/fix the content

### Create and test sample short descriptions

(Issue https://github.com/mdn/data/issues/261)

Write short descriptions for a small number (10) of CSS properties, and test how they would work in the different contexts they might appear in (an MDN page, an editor popup, a devtools widget).

On the basis of these samples:

1) draft some guidelines about how the short descriptions should be written
2) refine the estimates of how long it will take to update all of them.

### Update short descriptions for all CSS properties

Go through all the CSS property pages, checking that the summary is what we want: meaning, it's explicitly marked using "seoSummary", and contains the right content.

## Write a script to expose short descriptions in mdn/data

Write a script that works something like this:

* For each entry in the properties.json file in mdn/data:

a) Get the corresponding MDN page as a JSON object using the $json parameter (e.g. https://developer.mozilla.org/en-US/docs/Web/CSS/margin$json)

b) From this object, get the summary property, sanitize it to ensure it only contains the allowed elements and check that it's the correct length.

c) If the result is different from the current value of shortDescription in properties.json, then add it to a changelist.

* Open a PR against mdn/data containing the changelist.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the CSS property short descriptions wiki document, issue 261, and the properties.json file described in this issue. Review how MDN pages are retrieved through the $json parameter and how summaries should be sanitized and length-checked. Done means CSS property descriptions are checked and a script produces a changelist PR for differences in shortDescription.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
data, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.