[docs] Better docs for the Frictionless specs - esp overview and reference (may 2020)

On last week’s community call @cpina and @jen-thomas had some suggestions:

• An overview diagram for the Frictionless Specs showing how the key ones fit together
• A list of the key metadata fields in the spec (I remember the nodejitsu interactive guide and there’s stuff still online like http://jspkg.com/package_json)

Overview

I think some immediate things we could do:

• Add an overview diagram and intro e.g. like http://tech.datopian.com/frictionless/ to specs site
  • Maybe we want something like this on main site. I think maybe we want a /patterns/ or /specs/ page that provides an overview with subsections for key patterns (rather than separate pages for table schema and data packages like now).
• Categorize specs on specs site in e.g. menu: “Core” / Profiles / Extras (+ Patterns and security stuff separately)
  • Map of the specs in that overview section
• Make metadata fields into headings in specs so they are linkable (if not already)
• Table of contents at the start of specs

Reference

• A listing of all the main attributes per entity e.g. these are key attributes for a Data Package via @jen-thomas
  • e.g. http://package.json.nodejitsu.com/ (see my old now closed issue https://github.com/frictionlessdata/project/issues/94) or https://flaviocopes.com/package-json/
• A mapping of Frictionless specs against other metadata formats - cf frictionlessdata/forum#11 frictionlessdata/project#551 frictionlessdata/forum#48

Analysis

Goal: improve reference docs for Frictionless specs by extracting and displaying the metadata fields

Question: what tooling is there to visualize and display json schemas …

https://apievangelist.com/2019/07/10/the-json-schema-tooling-in-my-life/

ANS: does not mention anything

My googling gave me a few options. Two best were:

• http://sk-api-browser.herokuapp.com/ - this is best but is a a ruby app 😬 it works nicely and gives ideas on ux. Is there JS code one can reuse?
• http://jlblcc.github.io/json-schema-viewer/ - more visual orient so less useful IMO and could not work out how to load my own schema. Code is prob available but did not read.

[rufuspollock]

@jen-thomas @cpina - these are great suggestions and we’ll work on them. If you are around on Frictionless Fridays maybe we could co-work on this a bit with you giving feedback.

I’ve also refactored to include both improving overview and reference.

[jen-thomas]

Thanks @rufuspollock for the diagram - that will be very helpful I think. The overview of a data package makes it much clearer.

I have two suggestions for the Contribute section:

• I wasn’t sure what was meant by RFC-style. I did look on Wikipedia https://en.wikipedia.org/wiki/Request_for_Comments but to be honest I still wasn’t really clear how this was intended to be read in the context of an overview page. Perhaps something like, “Most work proceeds through discussions in the issue tracker.”?
• Perhaps a link to the Discord channel would be helpful for users that are put-off or overwhelmed by making suggestions or contributing through Github.