Adds missing user documentation for launch! (#1286)

Closes #1215 - Adds account settings page - Adds overview page - Adds archived items page - Adds note about browser profile metadata editing - Adds note on editing the crawler instances scale while crawling - Adds details on permission levels for the org settings - Removes note about not being able to change your display name (follows #1265)
webrecorder · Oct 17, 2023 · adf71f1 · adf71f1
1 parent a0def4f
commit adf71f1
Show file tree

Hide file tree

Showing 8 changed files with 95 additions and 5 deletions.
diff --git a/docs/user-guide/archived-items.md b/docs/user-guide/archived-items.md
@@ -0,0 +1,37 @@
+# Archived Items
+
+Archived Items consist of one or more WACZ files created by a Crawl Workflow, or uploaded to Browsertrix. They can be individually replayed, or combind with other Archived Items in a a [Collection](collections.md).  The Archived Items page lists all items in the organization.
+
+## Uploading Web Archives
+
+WACZ files can be given metadata and uploaded to Browsertrix by pressing the _Upload WACZ_ button on the Archived Items list page. Only one WACZ file can be uploaded at a time.
+
+## Archived Item Details
+
+The Archived Item details page is composed of five sections, though the Crawl Settings tab is only available for Crawls and not Uploads.
+
+### Overview
+
+The Overview tab displays the item's metadata and statistics associated with its creation process.
+
+Metadata can be edited by pressing the pencil icon at the top right of the metadata section to edit the item's description, tags, and collections it is associated with.
+
+### Replay
+
+The Replay tab displays the web content contained within the Archived Item.
+
+For more details on navigating web archives within ReplayWeb.page, see the [ReplayWeb.page user documentation.](https://replayweb.page/docs/exploring)
+
+### Files
+
+The Fies tab lists the individually downloadable WACZ files that make up the Archived Item as well as their file sizes.
+
+### Error Logs
+
+The Error Logs tab displays a list of errors encountered durring crawling. Clicking an errors in the list will reveal additional information.
+
+All log entries with that were recorded in the creation of the Archived Item can be downloaded in JSONL format by pressing the _Download Logs_ button.
+
+### Crawl Settings
+
+The Crawl Settings tab displays the Crawl Workflow configuration options that were used to generate the resulting Archived Item.
diff --git a/docs/user-guide/browser-profiles.md b/docs/user-guide/browser-profiles.md
@@ -27,3 +27,7 @@ Press the _Finish Browsing_ button to save the browser profile with a _Name_ and
 Sometimes websites will log users out or expire cookies after a period of time. In these cases, when crawling the browser profile can still be loaded but may not behave as it did when it was initially set up.
 
 To update the profile, go to the profile's details page and press the _Edit Browser Profile_ button to load and interact with the sites that need to be re-configured. When finished, press the _Save Browser Profile_ button to return to the profile's details page.
+
+### Editing Browser Profile Metadata
+
+To edit a browser profile's name and description, select _Edit Name and Description_ from the actions menu on the profile's details page.
diff --git a/docs/user-guide/crawl-workflows.md b/docs/user-guide/crawl-workflows.md
@@ -22,6 +22,12 @@ If the crawl queue is filled with URLs that should not be crawled, use the _Edit
 
 Exclusions added while crawling are applied to the same exclusion table saved in the workflow's settings and will be used the next time the crawl workflow is run unless they are manually removed.
 
+### Changing the Amount of Crawler Instances
+
+Like exclusions, the [crawler instance](../workflow-setup/#crawler-instances) scale can also be adjusted while crawling. On the Watch Crawl page, press the _Edit Crawler Instances_ button, and set the desired value.
+
+Unlike exclusions, this change will not be applied to future workflow runs.
+
 ## Ending a Crawl
 
 If a crawl workflow is not crawling websites as intended it may be preferable to end crawling operations and update the crawl workflow's settings before trying again. There are two operations to end crawls, available both on the workflow's details page, or as part of the actions menu in the workflow list.

diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md
@@ -10,9 +10,6 @@ If you have been sent an [invite](org-settings#members), enter a password and na
 
 If the server has enabled signups and you have been given a registration link, enter your email address, password, and name to create a new account. Your account will be added to the server's default organization.
 
-!!! note 
-    Names chosen on signup cannot be changed later.
-
 ---
 
 ## Start Crawling!

diff --git a/docs/user-guide/org-settings.md b/docs/user-guide/org-settings.md
@@ -1,15 +1,26 @@
 # Org Settings
 
-The Org Settings page is only available to organization Admins. It can be found in the main navigation menu.
+The Org Settings page is only available to organization admins. It can be found in the main navigation menu.
 
 ## Org Information
 
 This page lets you change the organization's name. This name must be unique.
 
 ## Members
 
-This page lists all current members who have access to the organization, as well as any invited members who have not yet accepted an invitation to join the organization. In the _Active Members_ table, Admins can change the permission level of all users in the organization, including other Admins. At least one user must be an Admin per-organization. Admins can also remove members by pressing the trash button.
+This page lists all current members who have access to the organization, as well as any invited members who have not yet accepted an invitation to join the organization. In the _Active Members_ table, Admins can change the permission level of all users in the organization, including other admins. At least one user must be an admin per-organization. Admins can also remove members by pressing the trash button.
 
 Admins can add new members to the organization by pressing the _Invite New Member_ button. Enter the email address associated with the user, select the appropriate role, and press _Invite_ to send a link to join the organization via email.
 
 Sent invites can be invalidated by pressing the trash button in the relevant _Pending Invites_ table row.
+
+### Permission Levels
+
+`Viewer`
+:   Users with the viewer role have read-only access to all material within the organization. They cannot create or edit Archived Items, Crawl Workflows, Browser Profiles or Collections.
+
+`Crawler`
+:   Users with the crawler role can create Crawl Workflows and Collections, but they cannot delete existing Archived Items that they were not responsible for creating.
+
+`Admin`
+:   Users with the administrator role have full access to the organization, including its settings page.
diff --git a/docs/user-guide/overview.md b/docs/user-guide/overview.md
@@ -0,0 +1,19 @@
+# Overview
+
+The overview page delivers key statistics about the organization's resource usage. It also lets users create crawl workflows, uploaded archived items, collections, and browser profiles through the _Create New ..._ button.
+
+## Storage
+
+For organizations with a set storage quota, the storage panel displays a visual breakdown of how much space the organization has left and how much has been taken up by all types of archived items and browser profiles. To view additional information about each item, hover over its section in the graph.
+
+For organizations with no storage limits the storage panel displays the total size and count of all types of archived items and browser profiles.
+
+For all organizations the storage panel displays the total number of archived items.
+
+## Crawling
+
+The crawling panel lists the amount of currently running and waiting crawls as well as the number of total pages captured.
+
+## Collections
+
+The collections panel displays the number of total collections and collections marked as sharable.
diff --git a/docs/user-guide/user-settings.md b/docs/user-guide/user-settings.md
@@ -0,0 +1,13 @@
+# Account Settings
+
+## Display Name
+
+This is the name that other users will see as yours in the application.
+
+## Email
+
+This is the email that you use to login. It is also what we'll use to contact you.
+
+## Password
+
+This is the password that you use to login. Passwords must meet a minimum security check. For more information on how we derive password security levels, see [zxcvbn](https://zxcvbn-ts.github.io/zxcvbn/guide/).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -57,13 +57,16 @@ nav:
       - develop/frontend-dev.md
       - develop/docs.md
   - User Guide:
+      - user-guide/overview.md
       - user-guide/index.md
       - Crawling:
         - user-guide/crawl-workflows.md
         - user-guide/workflow-setup.md
         - user-guide/browser-profiles.md
+      - user-guide/archived-items.md
       - user-guide/collections.md
       - user-guide/org-settings.md
+      - user-guide/user-settings.md
 
 markdown_extensions:
   - toc: