Idea: split out data reading functions into a separate, smaller package

[hrecht]

I'm very excited about this new package after years of manually pulling ArcGIS Online feature layers into R! Great work.

This is a big suggestion, but if there's ever the time to raise it, it's now while the package is brand new. I totally understand if there are good reasons not to do this.

I think there would be serious value in splitting the package into two: one with data reading and one with data writing/editing functions. There is a wide user base of people like me who frequently need to access ArcGIS layers but do not have user accounts and will never upload data to the portal. I'd bet there are a lot more potential users who will only ever using the reading functions than those who will only ever write or use both. Having readarcgis (or whatever it could be called) would make it much simpler for this big group of potential users who will read data but not write it. As of now, the package documentation and most of the functions relate to the writing side. Great for people who use them, but overkill to include for the rest of us!

For example, as a data journalist, I pull data from a lot of government agencies and research orgs - but pretty much no team in my field has an ESRI subscription ($$$, sorry!) Same goes for a lot of data analysts out there, students, researchers, etc. Having a package with just the reading functions would make it nice and lightweight, and I'd bet it would need far fewer updates than the writing functions side.

I can also imagine teaching an R workshop where I use example data from the API. It's much easier for new users to navigate and make sense of a package that's focused on the one main task than one that has a ton of functions that they won't use.

Again, I know that this would be a big shift, but I think it's worth considering while the package is still young.

[JosiahParry]

Thank you!!!! I think the chance of splitting the package in two is probably not going to happen for the foreseeable future. But I can foresee a future where we move all of the management stuff out into its own thing as that exapands. BUT your point is verrryyyy well taken.

The very first objective of this is reading data. @elipousson has done a lot of work on making it super simple and just 1 line of code to read data into memory via arc_read() (im going to get to #167 soon i promise). If possible, would you be able to walk through what your documentation consumption process was and which parts gave you the ick?

Ideally we can pump heavy into the sentiment of living atlas and all of the very many open data hubs that "theres literally so much data that is so free for you to use please use it" as the first thing that people are exposed to. Then, afterwards, tell folks that they can do all of their boring management work from R as well.

[hrecht]

Totally valid, like I said I know it's a big ask :) Kudos for all the great work on this, arc_read() worked like a charm.
The authorization sentence #172 was the first big point of confusion.

I love that reading data is the first objective of the package, and I think it just needs some clearer organization and wording. I think there's an opportunity to really highlight and clarify in the README and function reference that this package does two things: read data and write/edit data. The functionality is there, I think it's just a documentation organization question and could use some simple language written with the assumption that many potential users on the data reading side are totally unfamiliar with what the REST API is and what it can do.

The very first sentence of the README is "The goal of arcgislayers is to provide an R interface to the ArcGIS REST API ." To the uninitiated, that doesn't mean much. Something like "arcgislayers is an R package that lets users read data, edit, or create map layers hosted on ArcGIS Online. It is an R interface to the ArcGIS REST API developed by the ESRI team." ('m suggesting that last bit - if true, I think? - because there's real value in pointing out that this is an official product, not a third-party library. This is just a 5 second suggestion, I'm sure there's a better version.

Next, the README dives straight in with Creating a simple feature object from an ArcGIS FeatureLayer. I'd love to see two sections: first Reading data and second Writing (or editing or whatever the appropriate word is) data with very brief overviews. It would also be helpful to split the function reference into those sections - tidyr is a good example of that, having organized reference section groups. That would make it a lot easier to scan.

I'm only a few hours into this but am also a bit confused by when I'd want to use the get_layer functions vs arc_select vs arc_read. I think perhaps a vignette introducing users to reading data and the various options would be helpful. Written with the assumption that the user has no idea what a FeatureLayer or a FeatureServer or a MapServer is. I have been using the REST API occasionally for years and I'm still not totally clear on all the terms, so I think spelling that out and using plain language in the README, function reference, and a future vignette for data reading would be very helpful.

I'd prioritize the README and grouping the function references first - lowest hanging fruit!

[hrecht]

I'd also split up this entry: https://r.esri.com/arcgislayers/reference/utils.html

list_fields() seems super useful for data readers but is totally unrelated to refresh_layer() for example.

[JosiahParry]

This is SO helpful! Thank you so so so much <3