Add Comparison with SQL section to the user guide.

[ryancerf]

I use SQL a ton (mostly in my day job) and would like to help improve the user guide by adding a comparison with SQL section.

Pandas: has one and I find it pretty useful.

Should I wait for us to make some progress on #457?

[benmccann]

I don't have time to work on #457 myself. I'd be happy to review PRs though. But I'd want @lwhite1's feedback on the idea to make sure that's a direction we want to go

[lwhite1]

I would love to have better documentation. We could use a lot of documentation because the library is so big, but I'm not sure that this is the most important kind of documentation.

We often get criticized for insufficient and/or broken and out-dated documentation. To be at all manageable any documentation needs to be easy to maintain. Anything that will get out of date is probably more trouble than it's worth.

For the plots, there are some good example classes in the test folder in a package called examples. I have been thinking that the best documentation for them may be an index page pointing to the examples. Ideally this could be created by a script that reads the examples folder. If there was a naming convention for the classes and perhaps some grouping of related things into packages, it could be almost free after the setup. Bonus points would be executing a method on each class to produce the plot as an output file, and copying that file to a folder where it could be displayed.

A similar approach might work for core, minus all the plot-specific bits.

• an example folder under test
• sub packages based on feature
• a standard for organizing each class, maybe we could use a test method per example to ensure the code is at least executed occasionally.
• the description could be written as the method JavaDoc, and that could be put in the generated index file.
• a process for producing an index web page from the structure

You could perhaps include the code from the example in the output page in a code block. I suspect this could all be done with JavaDoc and doclets: https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/doclet/overview.html, but it might be fine to just use javadoc out of the box to start.

so something like:

• tables
  • creation
  • getting info
    • printing
    • structure
    • shape, rowCount, columnCount
    • columnNames
  • filters
    • simple where clauses
    • etc.

We could probably get by with this and a "getting started" example that runs through the most important features. It would also be easy to create a page on the differences with SQL and point to the relevant features.

[benmccann]

https://developer.lightbend.com/docs/paradox/current/ will let you embed Java files in markdown files. There might be other tools that allow this too. That could give us some ability to write nicely formatted text walking the user through the concepts. Though I don't know if anyone actually has time to do that

[ryancerf]

@lwhite1 Some good ideas. I agree the SQL stuff is a nice to have and can wait.

I am not super eager to do the setup for embedding Java files into markdown #457 , but once something is in place I will help the clean up the core docs.

Feel free to close this out. I can recreate it later if need be.