[
https://issues.apache.org/jira/browse/ARROW-2684?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16508643#comment-16508643
]
Wes McKinney commented on ARROW-2684:
-------------------------------------
Many of these criticisms are subjective -- I have learned over the years that I
have a different approach to programming pedagogy than some other people do. I
prefer to teach principles and concepts rather than starting from applications
/ concrete use cases and working backwards. I don't think statements like "the
examples are not practical" are constructive.
IMHO, the documentation should have both principles and discussion of low-level
concepts as well as more "cookbook" type of "get up and go" examples. Because
there is not a cookbook in the documentation does not mean that the other
documentation is bad.
I think we can create a number of JIRAs based on this feedback about adding
more documentation sections to address some of the common use cases to help new
users get up and running. We are all volunteers, so it may be a while until
someone else gets around to writing such documentation. We would definitely
welcome your assistance.
> [Python] Various documentation improvements
> -------------------------------------------
>
> Key: ARROW-2684
> URL: https://issues.apache.org/jira/browse/ARROW-2684
> Project: Apache Arrow
> Issue Type: Improvement
> Components: Python
> Reporter: Dominik Moritz
> Priority: Major
>
> The python documentation is currently not beginner friendly and things like
> the IPC format are not discoverable. For example,
> [https://arrow.apache.org/docs/python/ipc.html] has the word "IPC" only in
> the title. Also, it's currently not clear how to write a file to disk.
> I propose that the documentation becomes more of an API docs rather than a
> set of examples. Examples are valuable but they cannot replace documentation
> of the inputs and outputs of various functions.
> See [https://github.com/apache/arrow/issues/2119] for more.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
