search

odrw / reserved-words

Dictionary of Reserved Words (first attempt)
5 stars 0 forks source link

Best practices for using the dictionary #14

Open stuartpb opened 8 years ago

stuartpb commented 8 years ago

I'm going to commit what I currently have in docs/usage.md, but it's worded really confusingly (it's not clear that by "usage", I mean, like, flipping through the dictionary): the text direly needs some clarification (probably with some examples that make the guidelines less abstract).

stuartpb commented 8 years ago

In fact, docs/usage.md as it currently stands should probably be changed to docs/usage/naming.md - or something that clarifies "here are some best practices you should follow when you're using this dictionary as a guide to naming things in a system you're designing".

stuartpb commented 8 years ago

docs/usage/bikeshedding.md maybe? that's kind of the established term for this kind of naming concern - while it has pejorative connotations, it's also something W3C uses in earnest, and the straight definition ("coloring the bikeshed before the house is built") doesn't mean it's not useful (the pointer-events CSS property probably should have had a little more thought-before-building, for example).

stuartpb commented 8 years ago

I think docs/usage/specwriting.md covers it best, for now.

stuartpb commented 8 years ago

Eh... this kind of thing should probably just go in the Wiki, with a note that substantial changes should be discussed via an Issue first. It lets straightforward clarification and elaboration be low-friction and uninhibited, which is cool. (The flip-side, that people can screw up sensible advice by overwriting it with arbitrary assertions of belief, is an acceptable trade-off, considering the ease of reverting it and @mentioning them in an Issue discussing the reversion. Or something.)

stuartpb commented 8 years ago

https://github.com/opensets/reserved-words/wiki/Consulting-the-dictionary-when-naming-things