calcite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Julian Hyde <julianh...@gmail.com>
Subject Re: Calcite documentation
Date Fri, 13 Mar 2015 22:53:38 GMT
+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

Mime
View raw message