Improve documentation (#7)

* Document publication process

* Improve package documentation

Re-organize information so it is available in published packages

* Update packages/macos-at-driver-server/README.md

Co-authored-by: Stalgia Grigg <[email protected]>

* Reformat to satisfy linter

Unclear how this is an improvement

---------

Co-authored-by: Stalgia Grigg <[email protected]>

README.md

@@ -26,39 +26,6 @@ which is required by the automation voice.
 
 </details>
 
-## Installation
-
-1. Download the source code by executing the following command:
-
-       git clone https://github.com/w3c/aria-at-automation-driver.git
-
-2. Install the Node.js dependencies (from inside the project directory):
-
-       npm install
-
-3. Run the install command in a terminal (from inside the project directory):
-
-       ./shared/bin/at-driver install
-
-   If prompted for system administration permission, grant permission.
-
-4. Start the server by executing the following command in a terminal (from
-   inside the project directory):
-
-       ./shared/bin/at-driver serve
-
-   The process will write a message to the standard error stream when the
-   WebSocket server is listening for connections. The `--help` flag will cause
-   the command to output advanced usage instructions (e.g. `at-driver --help`).
-
-5. Configure any screen reader to use the synthesizer named "Microsoft Speech
-   API version 5" and the text-to-speech voice named "Bocoup Automation Voice."
-
-6. Use any WebSocket client to connect to the server. The protocol is described
-   below. (The server will print protocol messages to its standard error stream
-   for diagnostic purposes only. Neither the format nor the availability of
-   this output is guaranteed, making it inappropriate for external use.)
-
 ## Terminology
 
 - **message** - a [JSON](https://www.json.org)-formatted string that describes

packages/macos-at-driver-server/MAINTAINING.md

@@ -0,0 +1,16 @@
+# MacOS AT Driver Server Maintenance Guide
+
+This package organizes macOS platform code within an Xcode project. It also
+relies on Node.js code to expose a command-line interface; the Node.js code is
+copied into place from a shared directory during publication time.
+
+## Packaging Requirements
+
+- macOS version 13 ("Ventura") or later
+- Xcode
+- Node.js version 18 or later
+
+## Packaging Instructions
+
+1. Build the Xcode project
+2. Run `npm publish`

packages/macos-at-driver-server/README.md

@@ -0,0 +1,14 @@
+# MacOS AT Driver Server
+
+An implementation of the AT Driver "remote end" designed to work with screen
+readers on macOS.
+
+## Requirements
+
+- macOS version 13 ("Ventura") or later
+- Node.js version 18 or later
+
+## Usage
+
+For instructions on using this project's command-line interface, please refer
+to the `README.md` file located in the `shared` directory.

packages/macos-at-driver-server/package.json

@@ -5,7 +5,8 @@
   "license": "MIT",
   "description": "A WebSocket server which allows clients to observe the text enunciated by a screen reader and to simulate user input using macOS",
   "files": [
-    "MacOSATDriverServer",
+    "MacOSATDriverServer/Build/debug",
+    "README.md",
     "shared"
   ],
   "bin": {
@@ -14,5 +15,8 @@
   "scripts": {
     "prepack": "node ../../scripts/manage-shared.js copy",
     "postpack": "node ../../scripts/manage-shared.js cleanup"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
 }

shared/README.md

@@ -0,0 +1,23 @@
+# Command-line interface
+
+1.  Run the `install` sub-command in a terminal:
+
+        at-driver install
+
+    If prompted for system administration permission, grant permission.
+
+2.  Start the server by executing the `serve` sub-command in a terminal:
+
+        at-driver serve
+
+    The process will write a message to the standard error stream when the
+    WebSocket server is listening for connections. The `--help` flag will cause
+    the command to output advanced usage instructions (e.g. `at-driver --help`).
+
+3.  Configure any screen reader to use the synthesizer named "Microsoft Speech
+    API version 5" and the text-to-speech voice named "Bocoup Automation Voice."
+
+4.  Use any WebSocket client to connect to the server. The protocol is described
+    below. (The server will print protocol messages to its standard error stream
+    for diagnostic purposes only. Neither the format nor the availability of
+    this output is guaranteed, making it inappropriate for external use.)

shared/install/macos.js

@@ -139,7 +139,7 @@ const isInstalled = async function () {
  */
 const getExecOptions = async function () {
   return {
-    cwd: resolve(__dirname, '../../Release/macos'),
+    cwd: resolve(__dirname, '../../MacOSATDriverServer/Build/Debug'),
   };
 };