calcite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Milinda Pathirage <mpath...@umail.iu.edu>
Subject Re: Calcite documentation
Date Sat, 14 Mar 2015 13:15:30 GMT
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 <julianhyde@gmail.com> 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
> <lcolagiovanni@ebay.com> 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 <thartman@ebay.com> 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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message