#44 Linking to explanations/rationale behind spec features

Open
opened 1 month ago by fr33domlover · 0 comments

In the specs, when we require/state something, do we explain why a decision was made to model things in that way?

  • Specs that don't, are shorter, more concise, clean
  • Specs that do are easier to understand more deeply and extend, but they have much more text

IDEA: Much like Wikipedia pages have numbered reference links to all the info they state, we can put little cute links from the spec to issues and forum threads that discuss the specific feature/requirement/etc., that way the spec stays clean and things are explained.

In the AP spec there are a few notes about probably-added-late features, but mostly the whole rationale isn't explained. Lots of stuff surely exists in W3C work group meeting logs, and issues on their githu8 repo, but the info isn't linked from the spec. What if we put links, and help ourselves with the spec writing, and help others understand and participate in further improvement/polishing?

In the specs, when we require/state something, do we explain *why* a decision was made to model things in that way? - Specs that don't, are shorter, more concise, clean - Specs that do are easier to understand more deeply and extend, but they have much more text IDEA: Much like Wikipedia pages have numbered reference links to all the info they state, we can put little cute links from the spec to issues and forum threads that discuss the specific feature/requirement/etc., that way the spec stays clean *and* things are explained. In the AP spec there are a few notes about probably-added-late features, but mostly the whole rationale isn't explained. Lots of stuff surely exists in W3C work group meeting logs, and issues on their githu8 repo, but the info isn't linked from the spec. What if we put links, and help ourselves with the spec writing, and help others understand and participate in further improvement/polishing?
Sign in to join this conversation.
Loading...
Cancel
Save
There is no content yet.