mdn / short-descriptions

Short descriptions of web platform features, for flexible usage in applications.
Other
12 stars 6 forks source link

Add initial JSON entries #6

Closed ddbeck closed 5 years ago

ddbeck commented 5 years ago

This PR adds a few JSON entries for short descriptions that I've revised. I figure we'll work out how we want to layout the descriptions by revising this PR.

My initial approach was to simply dump the short descriptions into JSON files named for each CSS property. This has the benefit of easy-to-follow diffs (i.e., the list of files modified tells you which properties changed), at the expense of more files and a bit of JSON noise. Plus it was easy to do this (I've got the start of a script to write out wiki short descriptions to JSON now).

Some other approaches I considered but didn't exactly reject that might be worth considering, however:

This is a step toward fulfilling #5.

ddbeck commented 5 years ago

I do think it's a little redundant having a file, say, columns with a columns key in it. We could call it short_description perhaps? Or I wonder if we should adopt the BCD approach where every file contains the full path to the item

OK now that you've said this I think this is probably the right thing to do, instead of inventing our own structure. And since we're not planning on writing this stuff by hand, I think having more boilerplate isn't a huge problem. I pushed another commit that does this format and also fixed the missing newlines.