Improve doc

docs/writing-tests/wdspec.md

@@ -71,60 +71,65 @@ topic](https://docs.pytest.org/en/latest/fixture.html).
 ## WebDriver BiDi
 
 The wdspec tests for [WebDriver BiDi](https://w3c.github.io/webdriver-bidi) are 
-located in the `tests/bidi/` and `tests/interop` directory. The abstraction 
-`webdriver.bidi.client.BidiSession` represents the BiDi client and contains 
-properties corresponding to the 
-[WebDriver BiDi modules](https://w3c.github.io/webdriver-bidi/#protocol-modules).  
+located in the `tests/bidi/` and `tests/interop` directories. 
+The `webdriver.bidi.client.BidiSession` class provides an abstraction for the BiDi 
+client and contains properties corresponding to the 
+[WebDriver BiDi modules](https://w3c.github.io/webdriver-bidi/#protocol-modules). It 
+can be retrieved by fixture `bidi_session`.  
 
 ### Extending WebDriver BiDi
 
-This section describes extending WebDriver BiDi client in the example of adding 
-support for [Web Bluetooth](https://webbluetoothcg.github.io/web-bluetooth).
+This section describes how to extend the WebDriver BiDi client with an example of 
+adding support for [Web Bluetooth](https://webbluetoothcg.github.io/web-bluetooth).
 
-#### Adding new module
+#### Adding a New Module
 
 ##### Create `BidiModule`
 
-The BiDi modules are presented in `tools/webdriver/webdriver/bidi/modules/` 
-directory. In order to add new module `bluetooth`, declare a python class 
-`webdriver.bidi.modules.bluetooth.Bluetooth` inheriting from the `BidiModule`and 
+BiDi modules are defined in the `tools/webdriver/webdriver/bidi/modules/` directory.
+To add a new module called `bluetooth`, declare a Python class 
+`webdriver.bidi.modules.bluetooth.Bluetooth` that inherits from `BidiModule` and 
 store it in `tools/webdriver/webdriver/bidi/modules/bluetooth.py`:
+
 ```python
 class Bluetooth(BidiModule):
     """
-    Represents bluetooth automation module specified in
+    Represents the Bluetooth automation module specified in
     https://webbluetoothcg.github.io/web-bluetooth/#automated-testing
     """
     pass
 ```
 
-#### Import module in `bidi/modules/__init__.py`
+##### Import the Module in `bidi/modules/__init__.py`
+
+Import this class in `tools/webdriver/webdriver/bidi/modules/__init__.py`:
 
-This class 
-should be imported in `tools/webdriver/webdriver/bidi/modules/__init__.py`.
 ```python
 from .bluetooth import Bluetooth
 ```
 
-#### Create an instance of the module in `webdriver.bidi.client.BidiSession`
+##### Create an Instance of the Module in `webdriver.bidi.client.BidiSession`
+
+Modify the `webdriver.bidi.client.BidiSession.__init__` method to create an instance 
+of `Bluetooth` and store it in a `bluetooth` property:
 
-The `webdriver.bidi.client.BidiSession:__init__` method should create an instance of
-`Bluetooth` and store it in `bluetooth` property:
 ```python
 self.bluetooth = modules.Bluetooth(self)
 ```
 
-#### Adding new command
+#### Adding a New Command
+
+[WebDriver BiDi commands](https://w3c.github.io/webdriver-bidi/#commands) are 
+represented as module methods decorated with 
+`@command` (`webdriver.bidi.modules._module.command`). To add a new command, add 
+a method with the corresponding name (translated from camel case to snake case) to 
+the module. The method should return a dictionary that represents the 
+[command parameters](https://w3c.github.io/webdriver-bidi/#command-command-parameters).
+
+For example, to add the 
+[`bluetooth.simulateAdapter`](https://w3c.github.io/webdriver-bidi/#command-command-parameters)
+command, add the following `simulate_adapter` method to the `Bluetooth` class:
 
-The [WebDriver BiDi commands](https://w3c.github.io/webdriver-bidi/#commands) 
-are represented as module methods with `@command` decorator 
-(`webdriver.bidi.modules._module.command`). In order to add a new command, a method
-with the corresponding name (translated camel case to snake case) should be added to 
-the module. The method returns a dictionary which is used as 
-[command-parameters](https://w3c.github.io/webdriver-bidi/#command-command-parameters). 
-For example to add 
-[`bluetooth.simulateAdapter`](https://webbluetoothcg.github.io/web-bluetooth/#bluetooth-simulateAdapter-command) 
-command, add the following `simulate_adapter` method to `Bluetooth` class:
 ```python
 from ._module import command
 ...
@@ -138,12 +143,17 @@ class Bluetooth(BidiModule):
         }
 ```
 
-### Adding tests
+### Adding Tests
 
-Normally a single test file contains tests of a single parameter or feature. In 
-example of 
-[`bluetooth.simulateAdapter`](https://webbluetoothcg.github.io/web-bluetooth/#bluetooth-simulateAdapter-command), 
-it would make sense to split into:
+Generally, a single test file should contain tests for a single parameter or feature 
+and stored in `webdriver/tests/bidi/{MODULE}/{METHOD}/{FEATURE}.py`
+For example, tests for 
+[`bluetooth.simulateAdapter`](https://webbluetoothcg.github.io/web-bluetooth/#bluetooth-simulateAdapter-command) 
+could be split into:
 * Invalid parameters: `webdriver/tests/bidi/bluetooth/simulate_adapter/invalid.py`
 * State: `webdriver/tests/bidi/bluetooth/simulate_adapter/state.py`
 * Context: `webdriver/tests/bidi/bluetooth/simulate_adapter/context.py`
+
+In the example of [`bluetooth.simulateAdapter`](https://w3c.github.io/webdriver-bidi/#command-command-parameters), 
+tests can use `bidi_session.bluetooth.simulate_adapter` method to send the command 
+and verify its side effects.