Hi All, I did a quick prototype [1] for Calcite web + documentation. I used Jekyll[2] for generating [1]. If you prefer something like [1], I can work on that. Also, please feel free to comment on [1].
Source can be found at [3]. Thanks Milinda [1] http://milinda.pathirage.org/calcite-web-prototype/ [2] http://jekyllrb.com/ [3] https://github.com/milinda/calcite-docs-prototype On Fri, Mar 13, 2015 at 6:53 PM, Julian Hyde <[email protected]> wrote: > +1 > > This is much needed. In my view the best place to start is for people > to contribute a short article describing a particular task, e.g. "How > to write a user-defined function". > > Format doesn't matter. It could be a Word document or an email message > in all caps. The editor (say Trevor or whoever commits it) can easily > convert to the standard format. > > The standard format right now is markdown. See the existing docs in > https://github.com/apache/incubator-calcite/tree/master/doc. The task > of getting these onto the website is long overdue (mea culpa), but > that's an issue of presentation, and I think we should focus on > content. > > Julian > > > On Fri, Mar 13, 2015 at 1:28 PM, Colagiovanni, Lawrence > <[email protected]> wrote: > > It'd be awesome if you can make this happen. It sounds like the product > could really benefit from it, and I know it's an area you're passionate > about. > > > > > > > >> On Mar 13, 2015, at 13:09, Hartman, Trevor <[email protected]> wrote: > >> > >> I'd like to gauge interest from community members in writing > documentation for Calcite. If people are willing to write docs for topics > they understand well, I would be willing to help drive that process > (collect docs, make sure they're complete, present them cohesively, publish > them). > >> > >> I realize the code is well-documented at the package/class/method > level, and while that is great for reference, it's not ideal for > understanding big-picture concepts and how subsystems work together. > >> > >> I've been working with Calcite for nearly 6 months and feel like I've > barely scratched the surface in terms of understanding. I think some > well-written docs would encourage new users to learn Calcite as well as > help existing users take advantage of all Calcite has to offer, which in > turn encourages people to blog about it, speak about it, etc. > >> > >> Suggestions for topics I'm interested in include: > >> > >> - Overview of Calcite > >> - Conventions (enumerable, bindable, custom), traits > >> - Evaluating expression trees > >> - Pushing down operations, manipulating the relational expression tree > >> > >> Of course there are may other areas to document that I'm not even aware > of, and I'd be looking to you to help define that. > >> > >> - Are there any Apache standards for docs we should be aware of? > >> - Where do docs belong? I'm a big fan of in-repo docs written in > markdown, viewable on GitHub, but http://calcite.incubator.apache.org > might be the more appropriate location. > >> > >> I looked through jira to see if this work is already being tracked. > Nothing comprehensive, but here are some related issues: > >> > >> https://issues.apache.org/jira/browse/CALCITE-37 Document JSON model > file format > >> https://issues.apache.org/jira/browse/CALCITE-359 Publish javadoc > >> https://issues.apache.org/jira/browse/CALCITE-355 Create a web site > >> > >> Trevor > -- Milinda Pathirage PhD Student | Research Assistant School of Informatics and Computing | Data to Insight Center Indiana University twitter: milindalakmal skype: milinda.pathirage blog: http://milinda.pathirage.org
