Better docs esp overview and reference

[rufuspollock]

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 Interactive datapackage.json illustrator frictionlessdata.io#94) or https://flaviocopes.com/package-json/
• A mapping of Frictionless specs against other metadata formats - cf frictionlessdata/forum#11 Mapping data packages to DCAT2 frictionlessdata.io#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 i've done an update to https://specs.frictionlessdata.io/ to add an overview. Let me know what you think and what we could do next.

[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.

[cpina]

About diagram: it's very useful! I have two comments:

• in the second diagram (in https://specs.frictionlessdata.io/ just below "Example: How a Tabular Data Package is composed out of other specs"): each box (e.g. "Data resource", "Table schema", etc.) has a "Specification" with the name of the box on the left. One exception: "CSV Data Descriptor". I was matching the things that I know or that I remember and the links and this one is left. Actually the diagram boxes could be links to the spec of the box
• I can't remember if I or Jen mentioned this on the call but I sometimes miss a full example of a "Tabular data package" (or, even, per Spec type and then one together). E.g., here https://specs.frictionlessdata.io/data-package/#metadata there are snippets on each section but not a full real life example. The implementation of nodejitsu that you linked with the required fields, optional and explanations is very good. At some point something like this might be handy for new people to give context. I don't know if it should be part of the specs, as a Primer, tutorial, etc.

Thanks!

[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.

[cpina]

@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.

sure!