Tutorial dataset

[gampleman]

Since we seem to have some difficulty keeping our docs up to date or not misleading, I wonder if we could build something like this:

1. Produce a dataset with some nice interesting data (with clear labels, etc)
2. Add it as a data source called tutorial or demo that ships with cloak (perhaps as an embedded psql db ala shadow db)
3. Rewrite our example queries in the documentation to be against this dataset.
4. Run the queries against the dataset (on build or release) and verify that they actually work (or fail) as expected.
5. Have a button next to each example that would load the query in the Air interface allowing the reader to experiment with said query and see live results.

[fjab]

I really like this suggestion! We'll consider when is the best time to make it happen.

[sebastian]

Since we seem to have some difficulty keeping our docs up to date or not misleading

Wouldn't a meaningful safe guard against this be to have a mechanism in place which executes the queries we use in our docs? I.e. something like the regular doctests supported in Elixir? That way we ensure the examples actually are a) valid from a restrictions point of view, and b) don't rely on mechanisms we have deprecated.

[sebastian]

That being said: having a demo database that people can play and experiment with is useful in any case!

[fjab]

@sebastian I think that's what Jakub meant by

Run the queries against the dataset (on build or release) and verify that they actually work (or fail) as expected.

[sebastian]

Ah, yes, he spelled it out pretty clearly 😄 I was reading too fast.

[gampleman]

Another benefit of this would be that having a consistent dataset across all installations would make reproducing certain issues easier - as long as you can demonstrate the issue with the tutorial data source, anyone else can run the same query on their local version trivially.