[GitHub] [arrow] djnavarro commented on a diff in pull request #14514: ARROW-17887: [R][Doc][WIP] Improve readability of the Get Started and README pages

[GitBox <gi...@apache.org>]

djnavarro commented on code in PR #14514:
URL: https://github.com/apache/arrow/pull/14514#discussion_r1006121776


##########
r/vignettes/flight.Rmd:
##########
@@ -1,48 +1,38 @@
 ---
-title: "Connecting to Flight RPC Servers"
+title: "Connecting to a flight server"
+description: >
+  Learn how to efficiently stream Apache Arrow data objects across a 
+  network using Arrow Flight 
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{Connecting to Flight RPC Servers}
+  %\VignetteIndexEntry{Connecting to a flight server}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
 
-[**Flight**](https://arrow.apache.org/blog/2019/10/13/introducing-arrow-flight/)
-is a general-purpose client-server framework for high performance
-transport of large datasets over network interfaces, built as part of the
-[Apache Arrow](https://arrow.apache.org) project.
+[Arrow Flight](https://arrow.apache.org/blog/2019/10/13/introducing-arrow-flight/) is a general-purpose client-server framework for high performance transport of large datasets over network interfaces, built as part of the Apache Arrow project. It allows for highly efficient data transfer by several means:
 
-Flight allows for highly efficient data transfer as it:
+* Flight removes the need for deserialization during data transfer.
+* Flight allows for parallel data streaming.
+* Flight employs optimizations designed to take advantage of Arrow's columnar format.
 
-* removes the need for deserialization during data transfer
-* allows for parallel data streaming
-* is highly optimized to take advantage of Arrow's columnar format.
+The `arrow` package provides methods for connecting to Flight servers to send and receive data.

Review Comment:
   > In previous iterations of doc refactoring, we decided to refer to packages on the first instance with a link, and on the subsequent instances with a link to that package, instead of backticks as it makes the sentence more skimmable (and tbh were just copying [how the dplyr docs do it](https://dplyr.tidyverse.org/articles/programming.html) ;) ) There's a little bit in here about that: https://github.com/apache/arrow/blob/master/r/STYLE.md.
   
   Ah thanks -- I missed that. Thanks! I'll update 🙂 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org