adjust the wording

README.md

@@ -81,3 +81,7 @@ make integration-test
 ```shell
 make lint
 ```
+
+### Codegen
+
+Please consult the pages about [code generation](code-generation.md) and [how to add a new client](add-new-feature.md) to learn more about the architecture of the SDK.

internal/docs/add-new-feature.md

@@ -1,39 +1,41 @@
 # How to add a new client or method
 
-Let's assume we want to add a client for interacting with the workspace-related operations, such as creation, 
-modification, or deletion, as documented in the API.
+The SDK is modelling the namespaces from Xata's [API reference](https://xata.io/docs/api-reference/user), and creates a new client for each namespace. Example given, the `user` APIs listed in the [reference](https://xata.io/docs/api-reference/user) would be modelled in a `UserClient`.
 
-First, we need to ensure that the auto-generated code from the API definition exists. 
-For code generation see [here](code-generation.md). 
-The auto-generated code for the workspaces client is located in the 
-`xata/internal/fern-core/generated/go/workspaces_client.go` file. 
-`fern-core` is for the codes generated from the Core API. 
-`fern-workspace` is for the Workspace API.
+Let's assume we want to add a new client for interacting with the workspace-related operations, such as creation, 
+modification, or deletion, as documented in the [API reference](https://xata.io/docs/api-reference/workspaces). 
+This new client would contain the mentioned operations, modelled in a `WorkspaceClient`, see [workspaces_client.go](https://github.com/xataio/xata-go/blob/main/xata/workspaces_client.go) as a reference point.
+
+First, we need to ensure that the generated code from the API definition exists, for code generation consult [this guide](code-generation.md). 
+The generated code for the workspaces client is located in the `xata/internal/fern-core/generated/go/workspaces_client.go` file. 
+* `fern-core` is for the codes generated from the Core API
+* `fern-workspace` is for the Workspace API
 
 The files in the `xata/internal` folder are not accessible from the SDK. 
-For exposing any auto-generated code we need to create wrapper clients and their methods in the `xata` folder manually. 
-Each client lives in a dedicated file, i.e., `xata/workspaces_client.go.`
-The following code snippet shows how to create a `List` method on the workspaces client that actually points to 
-the auto-generated workspaces client, and it's `GetWorkspacesList` method.
+For exposing any generated code we need to create wrapper clients and their methods in the `xata` package manually. 
+Each client lives in a dedicated file, i.e., `xata/workspaces_client.go`.
+The wrappers have the purpose to create a leaner method names and allow for a level of complexity abstraction.
+The following code snippet shows how to create a `List` method on the workspace client that points to the generated workspace client, and it's `GetWorkspacesList` method.
+
 ```go
 type WorkspacesClient interface {
-List(ctx context.Context) (*xatagencore.GetWorkspacesListResponse, error)
-...
+    List(ctx context.Context) (*xatagencore.GetWorkspacesListResponse, error)
 }
 
 type workspaceCli struct {
-generated   xatagencore.WorkspacesClient
-workspaceID string
+    generated   xatagencore.WorkspacesClient
+    workspaceID string
 }
 
 func (w workspaceCli) List(ctx context.Context) (*xatagencore.GetWorkspacesListResponse, error) {
-return w.generated.GetWorkspacesList(ctx)
+    return w.generated.GetWorkspacesList(ctx)
 }
 ```
-In some cases, the auto-generated code might not be quite useful due to the code generation capability limitations. 
-In these cases, the manually generated wrapper code has to be expanded for a good user experience. 
-See the [records client](../../xata/records_client.go) as an example of such a scenario. 
-This might require modifying the auto-generated code, such as defining a new model or updating a method signature. 
+
+In some cases, the generated code might not be idomatic, due to limitations in code generation. 
+In these cases, the manually generated wrapper code has to be expanded for an improved user experience. 
+See the [RecordsClient](../../xata/records_client.go) as an example of such a scenario. 
+This might require modifying the generated code by hand, such as defining a new model or updating a method signature. 
 To be able to streamline the code generation process we need to incorporate these modifications via the 
 [`code_gen.go`](../../xata/internal/code-gen/code_gen.go) script that applies defined alterations on the 
-API definitions or the auto-generated Go code.
+API definitions or the generated Go code.

internal/docs/code-generation.md

@@ -1,21 +1,22 @@
-This SDK is a wrapper around an auto generated Go code from the OpenAPI specs.
-[Fern](https://github.com/fern-api/fern) is used for code generation.
+# Generating from OpenAPI spec
+
+This SDK is a wrapper around auto generated Go code from Xata [OpenAPI specs](https://xata.io/docs/rest-api/contexts#openapi-specifications). [Fern](https://github.com/fern-api/fern) is used for code generation.
 
 The process is automated with the following Make targets:
 
-Download the latest API specs
+Download the latest server OpenAPI specs
 ```shell
 make download-openapi-specs
 ```
 
-Generate code for CORE scope
+Generate code for `core` scope
 ```shell
-make generate-core-cod
+make generate-core-code
 ```
 
-Generate code for WORKSPACE scope
+Generate code for `workspace` scope
 ```shell
-make generate-workspace-cod
+make generate-workspace-code
 ```
 
 Code generation requires some updates in the API specs and auto-generated code for various reasons.