Merge pull request #101 from brown-ccv/second-pass

docs: Second pass for 3.3 documentation
brown-ccv · Feb 27, 2024 · 5d6def8 · 5d6def8
2 parents 1b7bc62 + 2359336
commit 5d6def8
Show file tree

Hide file tree

Showing 5 changed files with 44 additions and 100 deletions.
diff --git a/docs/deployments/firebase.mdx b/docs/deployments/firebase.mdx
@@ -43,15 +43,11 @@ The Firebase project is now fully set up! Now we'll connect your task to that pr
 
 The Firebase CLI is installed with the node package manager just like the rest of Honeycomb's dependencies. Be sure to log in with same account you used when logging into the console!
 
-```shell title="Install the Firebase CLI"
-npm install -g firebase-tools
-```
-
 ```shell title="Login to Firebase"
 firebase login
 ```
 
-_A `command not found` error usually indicates firebase-tools has not been installed correctly_
+_A `command not found` error usually indicates firebase-tools has not been installed correctly. Re-running `npm install -g firebase-tools` should fix this issue._
 
 ### Connecting Your Firebase Project
 
@@ -104,39 +100,6 @@ firebase deploy --only firestore:rules
 
 Your task is now connected to an initialized Firebase project!
 
-## Registering Studies
-
-:::caution
-This step must be followed **exactly**. See [Security Rules](#security-rules) for more information.
-:::
-
-1. Navigate to your Firestore Database in the [Firebase console](https://console.firebase.google.com/)
-2. Click "Start collection"
-3. Enter `registered_studies` for the collection id and click "next"
-4. Enter the id of your study for the document id
-5. Add a field named `registered_participants` with the type "array"
-6. Add the id of each study participant as a string inside the array
-
-<div style={{ textAlign: "center" }}>
-  <img
-    src={firestoreCreateStudy}
-    alt="Create a study"
-    style={{ maxHeight: "600px" }}
-  />
-</div>
-<br />
-
-The study should look like this when you're finished:
-
-<img
-  src={firestoreExampleStudy}
-  alt="Example study"
-/>
-<br />
-<br />
-
-**Additional studies must be created inside the `registered_studies` collection**
-
 ## Developing With Firebase
 
 _Two terminal windows must be used while developing for Firebase. See [here](https://code.visualstudio.com/docs/terminal/basics#_groups-split-panes) for instructions on splitting terminals in VSCode._
@@ -181,6 +144,39 @@ Firebase will update the files `firebase-hosting-pull-request.yml` and `firebase
   alt="Github actions created by firebase"
 />
 
+## Registering Studies
+
+:::caution
+This step must be followed **exactly**. See [Security Rules](#security-rules) for more information.
+:::
+
+1. Navigate to your Firestore Database in the [Firebase console](https://console.firebase.google.com/)
+2. Click "Start collection"
+3. Enter `registered_studies` for the collection id and click "next"
+4. Enter the id of your study for the document id
+5. Add a field named `registered_participants` with the type "array"
+6. Add the id of each study participant as a string inside the array
+
+<div style={{ textAlign: "center" }}>
+  <img
+    src={firestoreCreateStudy}
+    alt="Create a study"
+    style={{ maxHeight: "600px" }}
+  />
+</div>
+<br />
+
+The study should look like this when you're finished:
+
+<img
+  src={firestoreExampleStudy}
+  alt="Example study"
+/>
+<br />
+<br />
+
+**Additional studies must be created inside the `registered_studies` collection**
+
 ## Managing Data
 
 Honeycomb ships with a CLI script for managing data in Firebase. A local service account must be created in order to use it.

diff --git a/docs/introduction.mdx b/docs/introduction.mdx
@@ -5,7 +5,7 @@ title: Introduction
 description: Basic introduction to Honeycomb
 ---
 
-Honeycomb is an open source task-template repository that combines well-accepted practices and technologies from the cognitive science and web development communities to build psychophysiological tasks that are ready for deployment to different settings (desktop, or online) and support electrophysiological recordings, without significant changes to the code base.
+Honeycomb is an open source task-template repository that combines well-accepted practices and technologies from the cognitive science and web development communities to build psychophysiological tasks that support lab equipment recordings and are ready for deployment to different settings (desktop or online) without significant changes to the code base.
 
 ### Flexible deployment online and in the lab
 
@@ -17,7 +17,7 @@ Deployment specifications are abstracted as parameters that are easy to configur
 
 ### Foundation in jsPsych
 
-jsPsych 7 tasks can be converted to the Honeycomb structure to take advantage of the flexible deployment and automated GitHub Actions workflow that Honeycomb provides.
+Honeycomb is built on top of [jsPsych](https://www.jspsych.org/), a JavaScript library for running behavioral experiments in a web browser. jsPsych7 tasks can be moved directly into Honeycomb to take advantage of the flexible deployment and automated GitHub Actions workflow that Honeycomb provides.
 
 ### Cite this work
 

diff --git a/docs/prerequisites.mdx b/docs/prerequisites.mdx
@@ -63,7 +63,9 @@ Rosetta is a translation layer built for Mac computers with Apple Silicon. It sh
 The "Desktop development with C++" workload must also be installed with Visual Studio. The automated installers should preselect this but you should double check to be certain!
 :::
 
-## Manual Installation (macOS)
+## Manual Installation
+
+### macOS
 
 The links below will take you to each project installation page should you prefer to manually install the prerequisite software.
 
@@ -75,7 +77,7 @@ The links below will take you to each project installation page should you prefe
 - [VS Code](https://code.visualstudio.com/download)
 - [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12)
 
-## Manual Installation (Windows)
+### Windows
 
 The links below will take you to each project installation page should you prefer to manually install the prerequisite software.
 
@@ -89,7 +91,7 @@ The links below will take you to each project installation page should you prefe
   - [Visual Studio 2022 Community](https://visualstudio.microsoft.com/vs/community/)
   - Install the [Native C++ Workflow](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160#step-4---choose-workloads-1)
 
-## Manual Installation (Linux)
+### Linux
 
 The links below will take you to each project installation page should you prefer to manually install the prerequisite software. Your preferred installation method for the programs listed [above](#os-independent) should get you up and running on any Linux distro new enough to support GLIBC_2.28.
 

diff --git a/docs/quick_start.mdx b/docs/quick_start.mdx
@@ -219,7 +219,7 @@ Certain dependencies are best installed globally with Node. These tools will be
 npm install -g electron firebase-tools dotenv-cli
 ```
 
-## Run the Task in Development Mode
+## Run the Task
 
 Running the task in development mode causes it to hot-reload whenever changes are made to the app. This is how you'll run the project while building your task.
 
@@ -229,39 +229,6 @@ npm run dev
 
 This script launches an Electron window with the task and inspector open.
 
-You can quit the task in the middle of development if needed:
-
-<Tabs
-  groupId="os"
-  queryString
-  defaultValue="mac"
->
-  <TabItem
-    value="win"
-    label="Windows"
-  >
-    <kbd>Control</kbd> + W
-  </TabItem>
-  <TabItem
-    value="mac"
-    label="macOS"
-  >
-    <kbd>⌘</kbd> + Q
-  </TabItem>
-  <TabItem
-    value="linux"
-    label="Linux"
-  >
-    <kbd>Control</kbd> + W
-  </TabItem>
-</Tabs>
-
-### Saving data
-
-Data is saved throughout the task, even when running in development mode. The location of the task is logged at the beginning of the task wherever you ran `npm run dev`.
-
-Note how the data is organized by study and participant. Every run through of the task will save the data somewhere within this folder!
-
 ## Edit the Task
 
 Now that the task is up and running we can make our first changes to the code! We'll edit the `package.json` file to reflect your information.
@@ -291,8 +258,6 @@ Now that the task is up and running we can make our first changes to the code! W
 
 ## Next Steps
 
-Honeycomb tasks can be configured to run as a web app in Firebase, or as desktop application via electron. The desktop application can receive port signals from EEG, cameras, foot pedals, and more.
-
 The [Firebase](firebase) page explains how to set up your task with Firebase.
 
 To learn more about how to configure your task for these different scenarios, see [Environment Variables](environment_variables).

diff --git a/docs/troubleshooting.mdx b/docs/troubleshooting.mdx
@@ -7,28 +7,9 @@ description: Guide to troubleshooting some known errors and contacting the CCV w
 
 ## Inspecting Errors
 
-When developing Electron apps there are two processes: `main`, and `renderer`. In this case, `main` corresponds to `public/electron/main.js` and its console is in the terminal where `npm run dev`was run. `renderer` corresponds to the React App - this is everything else. The React app's console is in the app's window and can be seen in the dev tools. When running `npm run dev`, it should open by default.
+When running any of the `npm run dev` commands you may encounter errors. These may display over the window itself or may may exist in the developer tools. These tools can be accessed by right clicking the window and selecting "Inspect" or by pressing <kbd>Ctrl+Shift+I</kbd> (<kbd>Cmd+Option+I</kbd> on Mac). The errors, as well as any `console.log`s, will be displayed in the "Console" tab of the developer tools.
 
-In case you want to find out where the error is coming from when running the app locally:
-
-- Try reviewing logs in the terminal
-- Inspect element in your browser by opening your developer tools. For instance, in Chrome, this can be done via the menu View -> Developer or right-clicking and pressing inspect.
-
-## Testing in Linux
-
-When running `npm test` on Linux, you might get an error that mentions `ENOSPC`. This is because the test runner creates "watchers" for files in the project repo in order to automatically re-run tests as the files change. Linux limits the number of watchers that can be created at a time and the default limit may be smaller than the number of files in the repo.
-
-This is a "known issue" with some test runners on Linux, as in discussions [here](https://stackoverflow.com/questions/55763428/react-native-error-enospc-system-limit-for-number-of-file-watchers-reached) and [here](https://stackoverflow.com/questions/62206460/jest-watch-error-enospc-system-limit-for-number-of-file-watchers-reached).
-
-One simple workaround is to increase the number of allowed watchers (100000 seems to be sufficient):
-
-- Command that initially fails with `ENOSPC`: `npm test`
-- Check the configured limit on "watchers": `cat /proc/sys/fs/inotify/max_user_watches`
-- Edit the relevant Linux config file: `sudo vim /etc/sysctl.conf`
-- Add a line at the end of the config file: `fs.inotify.max_user_watches=100000`
-- Save, exit, and reload the config file: `sudo sysctl -p`
-- Check that the limit has changed: `cat /proc/sys/fs/inotify/max_user_watches`
-- Retry the initial command, which should now succeed: `npm test`
+When developing Electron apps there are two processes: `main`, and `renderer`. In this case, `main` corresponds to `public/electron/main.js` and its console is in the terminal where `npm run dev`was run. `renderer` corresponds to the React App - this is everything else. This console can be found using the same steps as above - note that running `npm run dev` should open the developer console by default.
 
 ## Common issues