chore: docs clarification (googleapis#1236)

rosiezou · web-flow · commit 847cec2dbbd4 · 2022-06-26T16:38:33.000-07:00
* chore: docs clarification

* addressed comments
diff --git a/README.rst b/README.rst
@@ -92,6 +92,19 @@ This section provides a brief overview of the Vertex AI SDK for Python. You can
 
 .. _vertex-ai-samples: https://github.com/GoogleCloudPlatform/vertex-ai-samples/tree/main/notebooks/community/sdk
 
+All publicly available SDK features can be found in the :code:`google/cloud/aiplatform` directory.
+Under the hood, Vertex SDK builds on top of GAPIC, which stands for Google API CodeGen.
+The GAPIC library code sits in :code:`google/cloud/aiplatform_v1` and :code:`google/cloud/aiplatform_v1beta1`,
+and it is auto-generated from Google's service proto files.
+
+For most developers' programmatic needs, they can follow these steps to figure out which libraries to import:
+
+1. Look through :code:`google/cloud/aiplatform` first -- Vertex SDK's APIs will almost always be easier to use and more concise comparing with GAPIC
+2. If the feature that you are looking for cannot be found there, look through :code:`aiplatform_v1` to see if it's available in GAPIC
+3. If it is still in beta phase, it will be available in :code:`aiplatform_v1beta1`
+
+If none of the above scenarios could help you find the right tools for your task, please feel free to open a github issue and send us a feature request.
+
 Importing
 ^^^^^^^^^
 SDK functionality can be used from the root of the package:
