diff --git a/docs/index.md b/docs/index.md
index bbb549a..b846679 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -4,10 +4,8 @@ _Structured extraction in Python, powered by OpenAI's function calling api, desi
 
 ---
 
-[Star us on Github!](www.github.com/jxnl/instructor).
-
 [![Downloads](https://img.shields.io/pypi/dm/instructor.svg)](https://pypi.python.org/pypi/instructor)
-[![GitHub stars](https://img.shields.io/github/stars/jxnl/instructor.svg)](https://github.com/jxnl/instructor/stargazers)
+![Star us on Github!](https://img.shields.io/github/stars/jxnl/instructor.svg?style=social)
 [![Documentation](https://img.shields.io/badge/docs-available-brightgreen)](https://jxnl.github.io/instructor)
 [![GitHub issues](https://img.shields.io/github/issues/jxnl/instructor.svg)](https://github.com/jxnl/instructor/issues)
 [![Twitter Follow](https://img.shields.io/twitter/follow/jxnlco?style=social)](https://twitter.com/jxnlco)
@@ -36,10 +34,12 @@ With Instructor, your code becomes more efficient and readable. Here’s a quick
 ## Usage
 
 ```py hl_lines="5 13"
-from openai import OpenAI
 import instructor
+from openai import OpenAI
+from pydantic import BaseModel
 
-# Enables `response_model`
+# This enables response_model keyword
+# from client.chat.completions.create
 client = instructor.patch(OpenAI())
 
 class UserDetail(BaseModel):
@@ -103,7 +103,7 @@ assert isinstance(model, UserExtract)
 
 ### Step 1: Patch the client
 
-First, import the required libraries and apply the patch function to the OpenAI module. This exposes new functionality with the response_model parameter.
+First, import the required libraries and apply the patch function to the OpenAI module. This allows us to parse the raw JSON from our OpenAI completions into Pydantic output.
 
 ```python
 import instructor
@@ -117,11 +117,9 @@ client = instructor.patch(OpenAI())
 
 ### Step 2: Define the Pydantic Model
 
-Create a Pydantic model to define the structure of the data you want to extract. This model will map directly to the information in the prompt.
+Create a Pydantic model to define the structure of the data extracted from the OpenAI response. This model will map directly to the information in the prompt.
 
 ```python
-from pydantic import BaseModel
-
 class UserDetail(BaseModel):
     name: str
     age: int
@@ -129,8 +127,7 @@ class UserDetail(BaseModel):
 
 ### Step 3: Extract
 
-Use the `client.chat.completions.create` method to send a prompt and extract the data into the Pydantic object. The response_model parameter specifies the Pydantic model to use for extraction. Its helpful to annotate the variable with the type of the response model.
-which will help your IDE provide autocomplete and spell check.
+Use the `client.chat.completions.create` method to generate a completion and extract response data into the Pydantic object. The response_model parameter enables autocomplete and spell check in your IDE.
 
 ```python
 user: UserDetail = client.chat.completions.create(
@@ -170,7 +167,7 @@ except ValidationError as e:
     print(e)
 ```
 
-Its important to not here that the error message is generated by the LLM, not the code, so it'll be helpful for re asking the model.
+Note, the error message is generated by the LLM, not the code, so it'll be helpful for re asking the model.
 
 ```plaintext
 1 validation error for QuestionAnswer