The OData Client docs are not self-contained: the first page someone sees is the "Basic CRUD operations" section, which begins with a code snippet that makes a query to the trip pin service using a generated proxy class. If this is a new user who wants to learn how to use the OData client, at this point they would be confused: What is DefaultContainer and where does it come from? Which namespaces do I import? What is context.People? How do you even install the library? How were the proxy clients generated? How would I adapt the code for my own service? etc.
The docs seem to assume that the user has prior experience with the Odata client library, code generation tools and TripPin service. Or it's assumed that the reader can find this information elsewhere, but in that case, there are no links provided either.
Proposed solution
I propose adding a "Getting started" section that introduces the OData client library and takes the user through installing the library and/or the connected service code generator and how to use it, and a basic overview of the classes generated and how to use them. This section should contain enough background information for the user to follow the remainder of the docs.
The problem
The OData Client docs are not self-contained: the first page someone sees is the "Basic CRUD operations" section, which begins with a code snippet that makes a query to the trip pin service using a generated proxy class. If this is a new user who wants to learn how to use the OData client, at this point they would be confused: What is
DefaultContainerand where does it come from? Which namespaces do I import? What iscontext.People? How do you even install the library? How were the proxy clients generated? How would I adapt the code for my own service? etc.The docs seem to assume that the user has prior experience with the Odata client library, code generation tools and TripPin service. Or it's assumed that the reader can find this information elsewhere, but in that case, there are no links provided either.
Proposed solution
I propose adding a "Getting started" section that introduces the OData client library and takes the user through installing the library and/or the connected service code generator and how to use it, and a basic overview of the classes generated and how to use them. This section should contain enough background information for the user to follow the remainder of the docs.