On Mar 16, 2015, at 10:31 AM, Hartman, Trevor <[email protected]> wrote:
> I created a parent jira item [1] to track all doc-related tasks along with an > initial sub-task to define a list of topics [2] with my initial suggestions. > I'd like to get some more feedback from committers on fleshing out the topic > list. > > @Milinda, that looks like a great start. I'm also a fan of Jekyll. +1 on the site and on Jekyll. > > @Julian, please let us know if there are specific processes you prefer (e.g. > whether to track docs tasks in jira, where the docs and src website should > live—should there be a "calcite" org on github for these sorts of repos?). There should not be a Calcite org — we are under Apache. Apache has integrated with github to a certain extent — for example, you can submit pull requests to https://github.com/apache/incubator-calcite/pulls, but the process we committers must use to close them is a little more complicated than usual. My preferred process would be to treat docs as code, that is, put documentation in markdown files in the doc directory, and submit pull requests for that doc. We value contributors who write documentation as highly as those who write code, so regular doc contributors are likely to be invited to become committers. Moving to jekyll makes sense, because it will allow us to easily deploy our docs as part of the web site. The mechanism of deploying the web site requires checking files into subversion[1] but only one or two committers need to worry about that. For everyone else, the source of the documentation is git. Let’s brainstorm on this list to find a list of initial topics and the authors to write them, and we can paste into https://issues.apache.org/jira/browse/CALCITE-622 when we have consensus. To start, here is Trevor’s list: • (a) Overview of Calcite • (b) Conventions (enumerable, bindable, custom), traits • (c) Evaluating expression trees (via compilation, via interpretation) • (d) Pushing down operations, manipulating the relational expression tree I would add: (e) The standard relational expressions (f) Overview of planning concepts (RelNode, rule, trait, convention, metadata) (covers b) (g) The lifecycle of a query, from parsing to execution (covers c) (h) Enumerable convention (expands on g) (i) Bindable convention and the interpreter (expands on g) I am not volunteering to write any of these (we tried that strategy, and look where it got us!). If it would help, I’m happy to be “interviewed” over Skype or google hangouts. Julian [1] svnpubsub, https://www.apache.org/dev/project-site.html#svnpubsub
