Doc issues in "Interactive Data Exploration with Altair"

[darryl]

It’s unclear where doc bugs are supposed to be reported (oh please why can’t I do that from the doc pages?).

Anyhow Interactive Data Exploration with Altair - OmniSci Docs has multiple problems.

There is a section titled “Adding Interactivity” which has nothing to do with “Interactivity” or adding it. It’s about basic connection to an OmniSci database. Why not just call it that… “tool tips” at the end are just a silly example of “interactivity”. Get people started with the basic charts (without issues below) is much more important, and then maybe add more chart type examples and then futz with “interactivity”.

And the first two code fragments in that section don’t match the surrounding text. Like “Here is a chart definition using Altair” is not preceding a chart definition, it’s preceding what looks like an unintended near duplicate of the previous code example… except the second one has a typo, if the connection object is meant to be omnisci_cli then it needs to also use t = omnisci_cli.table(). I suspect somebody is just copying and pasting code samples without testing they work, come on, please automate testing of code samples in docs.

Maybe it would be better to put doc effort into doc and samples in Jupyter notebooks.

[candido.dessanti]

Hi @darryl,

Thanks for pointing us to the redundant connection example (that’s also broken, as you said) with the wrong surrounding text; I guess something had gone wrong when we moved to the new version of the docs.

About interactivity, in my opinion, the author has attempted to highlight that data comes from a live database, where data can be changed, than a fixed data frame.

As we are constantly improving the core of our database, we will put more effort into the docs and samples provided with the software.

Thanks again to reporting the issue.

Regards,
Candido

[darryl]

The use of “interactivity” here is a utter mess and if the author intended to mean it just connects to a database they need serious help. Has OmniSci brain-sporked itself with overuse of “interactive” as a marketing term? There is nothing to a user that is interactive about a static chart coming from a database. And none of the examples in that section had any on-screen interactivity, the kind of thing that might show the power of OmniSci. The only interactivity was a silly roll-over. You guys are just ruining your own positioning with stuff like this.

The Altair and Vega doc makes clear sensible specific use of “interactive” and provides some nice interactive chart examples e.g. Example Gallery — Altair 4.1.0 documentation. I would hope OmniSci use would align with that sensible usage. Even maybe present more of the same interactive chart examples on OmniSci/Jupyter as well as showing cases where OmniSciDB can shine bringing more back-end horsepower.

I highlighted one page of doc, but the overall documentation in this area and notebooks has some very nice stuff scattered around in it, but it’s ruined by lack of better overall flow, clear messaging and I suspect more basic examples using Altair. It looks and feels like what I expect it is, a scattered collection of stuff pulled from different authors and sources and could be better designed to help users get going and use the product. And again, all of that doc I expect should be in Jupyter notebooks (or reproduce that exact content elsewhere if really needed), right now you have two confusing/competing sets of doc.

And you folks have Jupyter notebooks, do your nightly build and release QA against those notebooks .