Update guides to Frictionless Data specifications v1

[serahkiburu]

From @danfowler on December 2, 2016 19:38

This is an issue for updating the current user guides.

We need at least two (related) types of guides for Data Packages: one set oriented toward users (developers, publishers, and consumers of data) and one set for implementors (developers seeking to create new implementations).

User Guides

This is a set of guides for publishers and consumers of data using the tools that exist. They should collectively answer the question "how do I X with a Data Package?". As there are many tools (some with overlapping functionality), it is important that this set of guides is oriented from a "use case" standpoint rather than a tool-specific one. We should also show how these tools fit together, because it is not always obvious.

Problems

• They are out of date w/r/t tools
• They are out of date w/r/t specs
• They are not super well organized
• It is not obvious how to contribute (more implementations will come and need user-friendly guidance)

Requirements

• It must be clear that these are "user" and not "implementor" guides with clear guidance on where to go to find information on implementions
• The guides must reflect the current state of Data Package tooling and be easy to update
• They should list the date published and the version of Data Packages they target so that readers can be reasonable confident that they are reading up-to-date information
• The URL structure must be flexible enough to allow for multiple use cases/languages
• It should be easy to contribute new guides for new languages (e.g. related to tool-fund)
• The user guide must pull from a stable and illustrative set of updated Data Packages for examples: (e.g. https://github.com/frictionlessdata/example-data-packages or
• Contributor of guide should be listed

Tasks

• Decide on home: these could continue to be listed under /guides/ or moved to a github repo alongside the implementations github repo
• List use cases to target (e.g. reading metadata from a Data Package, downloading a Data Package to disk, importing a Data Package into an SQL interface, exporting a Data Package from an SQL interface, creating a Data Package, validating a Data Package for adherence to spec, validating the data within a Data Package. updating a Data Package, joining fields in two Data Packages, etc.)
• For each use case with a clear guide that can be written to address it, create a /guides/{use-case}/{interface} where {use-case} can be something like validating-data or sql and {interface} can be something like python, javascript, cli, or webapp.
  • Link to pilots (e.g. https://github.com/frictionlessdata/pilot-dm4t) where appropriate
• Translate the existing guides to Jupyter notebooks following the above format
• Create guidance to update or add to guides for other languages/interfaces
• Other Cleanup
  • Remove link to http://frictionlessdata.io/tools/
  • Remove link to JSON Wikipedia

#examples
/guides/working-with-sql/python/
/guides/working-with-sql/ruby/
/guides/validating-data/python
/guides/validating-data/goodtables-io
/guides/creating/javascript

Implementors Guide

• Merge these three:
  • https://github.com/frictionlessdata/implementations/
  • http://specs.frictionlessdata.io/implementation/
  • http://frictionlessdata.io/guides/developer-guide/

Copied from original issue: frictionlessdata/frictionlessdata.io#332

[serahkiburu]

From @danfowler on December 12, 2016 13:39

Renamed to reflect that we will do all this communication after the V1 release.

[serahkiburu]

From @pwalsh on March 16, 2017 20:59

@danfowler now based on frictionlessdata/frictionlessdata.io#341 being ready for you, and based on @roll starting next Monday on js and py updates for v1, I think you could start a branch that does this - updating our guides for v1. This will, along with the work that @roll will start next week, help us all pick out more issues in the specs and get them tip top.

[serahkiburu]

From @Stephen-Gates on June 14, 2017 6:50

I made a start at https://discuss.okfn.org/t/tutorial-for-handcrafting-a-table-schema/5577
Happy to review, test or author some guides. Let me know the framework for contributions and I'll fit in. In the meantime, I'll write some stuff in Google Docs.

[serahkiburu]

From @danfowler on June 14, 2017 8:11

• How to make a README.md for a dataset stored on GitHub: https://discuss.okfn.org/t/readme-md-practice-for-data-packages/5555

[serahkiburu]

From @Stephen-Gates on June 14, 2017 10:6

I'm also scribbling notes about Tabular location data. Contributions welcome - very draft at present.

[serahkiburu]

From @pwalsh on June 15, 2017 7:26

@danfowler can you move this issue to https://github.com/frictionlessdata/frictionlessdata.io/issues

[serahkiburu]

From @pwalsh on June 15, 2017 7:27

@danfowler specifically, to this issue that already exists frictionlessdata/frictionlessdata.io#114

[serahkiburu]

From @roll on November 15, 2017 6:52

@serahrono
@vitorbaptista
If we're back for an active usage of this issue track I think we need to update/close this issue. Probably many of these steps are already done. And those that not done but actual we could extract as things to do.