search

osmlab / editor-layer-index

A unified layer index for OSM editors.
https://osmlab.github.io/editor-layer-index/
Other
220 stars 258 forks source link

Human readable schema #562

Open andrewharvey opened 6 years ago

andrewharvey commented 6 years ago

There is a schema https://github.com/osmlab/editor-layer-index/blob/gh-pages/schema.json and although it's fairly easy to read as a human, it's still a machine readable document.

Are there any thoughts about turning this into a markdown or something and incorporating it into the existing CONTRIBUTING.md?

bhousel commented 6 years ago

Love this idea.. I'm always in favor of improving documentation to lower the barriers to contribution.

I feel like in a JSON Schema, each property should have a description to say how the property should be used, and optionally a $comment if the field needs more explanation.

We should also update the contributing.md to answer any questions that a beginner might have.

(here's another project, where I have the schema and contributing document set up mostly how I like it) https://github.com/osmlab/osm-community-index/blob/master/schema/resource.json https://github.com/osmlab/osm-community-index/blob/master/CONTRIBUTING.md#resources