search

awsdocs / amazon-rds-user-guide

The open source version of the Amazon RDS docs. You can submit feedback & requests for changes by submitting issues in this repo or by making proposed changes & submitting a pull request.
Other
150 stars 231 forks source link

"Working with PostGIS" documentation a little misleading #94

Closed adamchainz closed 3 years ago

adamchainz commented 4 years ago

The Working with PostGIS guide is a little misleading. It's not setting up only the postgis extension, but also the extras fuzzystrmatch, postgis_tiger_geocoder, and postgis_topology.

Loading these extras is unnecessary for applications that only use basic PostGIS functionality. This includes the popular Django GIS extension which is what I am looking at setting up.

I suggest it be split into two guides: PostGIS (basically only CREATE EXTENSION IF NOT EXISTS postgis, and the PostGIS extras.

randyurbano commented 3 years ago

Thanks for your feedback, and sorry about the delay in responding. After discussing it with the service team, we decided not to split this documentation.

adamchainz commented 3 years ago

You could at least add a sentence that not all the extra extensions are required in all use cases?

randyurbano commented 3 years ago

Yes, I can add that to the documentation. Thanks again for your feedback.

ardentperf commented 3 years ago

I'm not super deep on PostGIS, but it definitely does seem accurate to say that all the other extensions listed in that example are dependents and you technically don't need to install them, unless you need their functionality. That said, one advantage of listing all the dependents in the example is that it might be helpful for people who don't know much about PostGIS yet. ISTM that the PostGIS community docs themselves should probably be the canonical reference for questions like when to install which extensions - and FWIW those docs are linked at the top.

I do think that one really important thing for RDS docs would be to call out any specific quirks of running PostGIS on RDS (most notably, things related to the privilege model being different - the existence of "rds_superuser" role while not having core PostgreSQL superuser)

I'm not a doc writer either but having good docs (clear, concise, useful, thorough) seems to me like almost just as much of an art as a science; the approach settled on here seems reasonable to me FWIW - adding a note to the bottom about the extensions not being needed in all use cases.

randyurbano commented 3 years ago

The note is in the public documentation now:

https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.PostGIS.html#Appendix.PostgreSQL.CommonDBATasks.PostGIS.LoadExtensions