feat: improve readability of readme documentation

README.md

@@ -6,13 +6,11 @@ Puts a small, bored cat, an enthusiastic dog, a feisty snake, a rubber duck, or
 
 [![Visual Studio Marketplace Version](https://img.shields.io/visual-studio-marketplace/v/tonybaloney.vscode-pets?color=blue&logo=visual-studio)](https://marketplace.visualstudio.com/items?itemName=tonybaloney.vscode-pets&WT.mc_id=python-17801-anthonyshaw)
 
-Run the "Start pet coding session" action to see the panel.
-
 ![screenshot](https://github.com/tonybaloney/vscode-pets/raw/master/screenshots/screenshot.gif)
 
 ## Installation
 
-Get from the [VS Code marketplace](https://marketplace.visualstudio.com/items?itemName=tonybaloney.vscode-pets&WT.mc_id=python-17801-anthonyshaw).
+Install this extension from the [VS Code marketplace](https://marketplace.visualstudio.com/items?itemName=tonybaloney.vscode-pets&WT.mc_id=python-17801-anthonyshaw).
 
 OR
 
@@ -24,14 +22,27 @@ With VS Code open, launch VS Code Quick Open (`Ctrl+P` on Windows/Linux or `Cmd(
 
 `ext install tonybaloney.vscode-pets`
 
-## Showing your pet
-Open the command palette with `Ctrl+Shift+P` on Windows/Linux or `Cmd(⌘)+Shift+P` on MacOS.  
+## Using VS Code Pets
+Congrats on installing joy! Enjoy interacting with these cute pixelated pets. Read below to get a full understanding of this extension. 
 
-Run the "Start pet coding session" command (`vscode-pets.start`)
+Available commands are prefaced with `Pet Coding` in the Command Palette:
+* Start pet coding session
+* Spawn extra pet
+* Remove pet
+* Roll-call
+* Remove all pets
+* Throw ball
+
+## Configure vscode-pets in the VS Code settings
+Open the setting panel with `Ctrl + ,` on Windows/Linux. In the search bar, enter “vscode-pets” to see all available options.
 
-## Configuring your pet
+Set a default color, size, pet type, position, and theme when you open a Pet Panel.
 
-You can choose either pet type and pet color:
+* Pet Color: black, brown, green, yellow, gray, red, white
+* Pet Size: nano, medium, large
+* Pet Type: cat, crab, clippy, cockatiel, dog, rocky, rubber duck, snake, totoro, zappy
+* Position: panel, explorer
+* Theme: none, forest, castle, beach
 
 ![screenshot2](https://github.com/tonybaloney/vscode-pets/raw/master/screenshots/screenshot-2.gif)
 
@@ -40,9 +51,14 @@ You can choose either pet type and pet color:
 * Ferris the crab can only be red
 * Rocky can only be gray
 
+## Start pet coding session to show your pet
+Open the command palette with `Ctrl+Shift+P` on Windows/Linux or `Cmd(⌘)+Shift+P` on MacOS.  
+
+Run the "Start pet coding session" command (`vscode-pets.start`)
+
 ## Playing
 
-Pets will interact with you within the open Pet Panel.
+Pets will interact with your mouse pointer within the open Pet Panel.
 
 ![screenshot3](https://github.com/tonybaloney/vscode-pets/raw/master/screenshots/screenshot-3.gif)
 
@@ -60,12 +76,18 @@ Run the "Spawn additional pet" command (`vscode-pets.spawn-pet`) and select the
 
 Extra pets will not persist between closing and restarting VS Code.
 
+![pet-select](https://github.com/tonybaloney/vscode-pets/raw/master/screenshots/pet-select.png)
+
 ## Removing pets
 
 You can remove all pets (except the 1 configured) by running the "Remove all pets" command (`vscode-pets.delete-pets`) from the command palette.
 
 You can remove specific pets by running the "Remove pet" command (`vscode-pets.delete-pet`) from the command palette.
 
+## Roll-call with your pets
+
+Get a description of your current pets within VS Code. 
+
 ## Themes
 
 Configure `vscode-pets.theme` to `"forest"` and let your pets play in a spooky forest.
@@ -80,10 +102,6 @@ Set `vscode-pets.theme` to `"beach"` for your friends to play by the ocean.
 
 ![beach](https://github.com/tonybaloney/vscode-pets/raw/master/screenshots/beach-pose.png)
 
-## More options
-
-From the VSCode preferences, search for **vscode-pets** for more options. In particular you can move the panel to the sidebar, or change the pet type and theme.
-
 ## Contributing
 
 ### Ideas and discussion
@@ -92,7 +110,7 @@ Have an awesome idea for a new feature? Please [open an issue](https://github.co
 
 ### Reporting bugs
 
-Something is not working as it should? Please [open an issue](https://github.com/tonybaloney/vscode-pets/issues/new) giving as much information as you can. Writing an effective bug report is a valueable skill as a Software Engineer, refer to the given example below for advice.
+Something is not working as it should? Please [open an issue](https://github.com/tonybaloney/vscode-pets/issues/new) giving as much information as you can. Writing an effective bug report is a valuable skill as a Software Engineer, refer to the given example below for advice.
 
 **Title** - Clearly summarize what the bug is with specific details.  
 **Summary** - If the title is too long, include a summary with additional details.  
@@ -117,8 +135,20 @@ Sandboxed: No
 
 Want to contribute to vscode-pets? Feel free to [fork the repository](https://github.com/tonybaloney/vscode-pets/fork) and submit a pull request.
 
-#### Testing the changes
+### Drawing and Animations
+If you want to contribute improvements to the animations, additional pet colors or even new pets, clone the repository and work in the media/ folder.  
+
+Most drawings are done in aseprite because you can edit the GIFs directly. However, use any tool to make the animations. Animations should be 8 frames per second. The style of the extension is to have pixelated creatures (although not limited to an 8-bit color canvas).  
+
+Don't worry if you don't have enough coding experience to add the changes to the extension to support the new animations, we can help you with that.  
+
+The minimum set of behaviors is:
+* standing
+* walking
+* running/chasing
+* holding green ball
 
+### Testing the changes  
 -   Run `npm install`.
 -   Run `npm run compile`.
 -   Go to the debug panel on the sidebar and launch the development version with the extension loaded (first option in the debug profiles).