significant revisions made to the docs

docs/gameboard/admin-practice-area.md

@@ -10,11 +10,17 @@ More information about Markdown, including the syntax guide, can be found at [ma
 
 ## Suggested Searches
 
+Suggested searches appear on the Practice Area homepage just below the greeting and direct players to useful or interesting subsets of available practice challenges. These searches act as filters for tags attached to a challenge. (When a challenge is created, the developer can optionally add tags that describe the skills needed to solve the challenge.)
+
+Only tags that match the suggested searches are displayed to the player when browsing the Practice Area. This ensures players see relevant tags that help them find the challenges they are interested in.
+
+To enter suggested searches, list one search term per line.
+
 ## Certificate Template
 
 Admins configure the certificate template here by entering HTML into the **Certificate Template** field. Players save certificates in PDF format for each practice challenge they fully complete. More information on certificates can be found in the [Playing in the Gameboard](./participating.md) documentation under "The Profile screen" heading.
 
-For your convenience, here are several variables you can include in your template to display information about the player's performance on a practice challenge.
+For your convenience, here are several variables you can include in your template to display information about the player's performance on a practice challenge. 
 
 - `{{playerName}}`: The player's approved username
 - `{{score}}`: The player's score on the challenge
@@ -24,6 +30,8 @@ For your convenience, here are several variables you can include in your templat
 - `{{track}}`: The track the challenge was originally placed in competitive mode
 - `{{time}}`: The amount of time the player spent solving the challenge
 
+Additional information about using these variables can be found by clicking the *How do I create a certificate template?* link.
+
 ## Session Limits
 
 Admins use these controls to set limits on practice sessions, including:

docs/gameboard/index.md

@@ -1,6 +1,6 @@
-# Gameboard Docs
+# About the Gameboard
 
-Developed by Carnegie Mellon University's [Software Engineering Institute](github.com/cmu-sei) (SEI), Gameboard is a flexible web platform that provides game design capabilities and a competition-ready user interface. *Gameboard Docs* explains how to implement it when you want to run your own cybersecurity game.
+Developed by Carnegie Mellon University's [Software Engineering Institute](github.com/cmu-sei) (SEI), Gameboard is a flexible web platform that provides game design capabilities and a competition-ready user interface. The *Gameboard * explains how to implement it when you want to run your own cybersecurity game.
 
 ## Gameboard concepts
 
@@ -10,12 +10,4 @@ Developed by Carnegie Mellon University's [Software Engineering Institute](githu
 
 *Participated* vs. *played*:  These terms are interchangeable -- a user who has enrolled in a game and launched a challenge has participated or played.
 
-*Sponsor*: Describes the organization a player is associated with. In a government-sponsored competition like the President's Cup, a sponsor may be a department (e.g., Department of Homeland Security, Department of Defense). In a school-sponsored competition, you may choose to have different universities represented as sponsors (e.g., Carnegie Mellon University, University of Pittsburgh).
-
-<!--## Gameboard concepts
-
-*Registering* is when...
-
-*Enrolling* is when...
-
-A *session* is when a player ... -->
+*Sponsor*: Describes the organization a player is associated with. In a government-sponsored competition like the President's Cup, a sponsor may be a department (e.g., Department of Homeland Security, Department of Defense). In a school-sponsored competition, you may choose to have different universities represented as sponsors (e.g., Carnegie Mellon University, University of Pittsburgh).

docs/gameboard/participating.md

@@ -1,4 +1,4 @@
-# Playing in the Gameboard
+# Participating in a Game
 
 This topic describes the Gameboard from a participant's point-of-view. A *participant* is a player in a game or a competitor in a competition who has no special role(s) attached them. These instructions assume that a fully configured game environment is available to the reader and they have an account on the Identity server.
 
@@ -11,16 +11,22 @@ This topic describes the Gameboard from a participant's point-of-view. A *partic
 
 ## The Profile screen
 
+**Display Name:** Set a default name for public display that is suitable for all audiences. This name will apply to all new games, however, you can customize it during registration.
+
+**Sponsoring organization:** Select *your* organization. Gameboard admins define who the sponsors are and what image to associate with each.
+
 **Certificates:** View and print a certificate as proof of participation. This feature allows players to provide a record of achievements to friends, colleagues, and organizations to validate professional development time. Select **Competitive** to find and print certificates which validate player performance in a *game*. Select **Practice** to find and print certificates which validate player performance in a *practice challenge*. You can also save them as PDFs. 
 
 - **Publish/Unpublish:** Optionally "publish" a certificate on a per-certificate basis. Players can send the link to the certificate to anyone including non-Gameboard users. Players can "unpublish" a certificate at any time removing access to the certificate.
 - **Open:** Launches the certificate in a new tab in the browser.
 
 **History:** View game history, including where you finished on the scoreboard and whether it was in practice or competition.
 
-**Display Name:** Set a default name for public display that is suitable for all audiences. This name will apply to all new games, however, you can customize it during registration.
+**Settings:** 
 
-**Sponsoring organization:** Select *your* organization. Gameboard admins define who the sponsors are and what image to associate with each.
+Users with the appropriate permissions (`Support` and `Admin`) may opt to receive browser notifications when support tickets are opened, closed, and updated. Users can choose to play an audio alert when a browser notification is received. 
+
+Browser notifications are subject to OS-level settings which may need to be changed and browser site settings for pop-ups and redirects which need to be allowed.
 
 ## The Home screen
 
@@ -47,7 +53,7 @@ If the game is a team game, you organize your team in the game lobby. Under **Se
 To start your session, click **Start Session** and click through the confirmation messages.
 
 !!! warning
-    For team players, make sure your teammates are ready to start. You can't add or remove team members after your session has started. Also note that *any* team member can start a session -- the continuous session timer starts when **Start Session** is clicked.  
+    For team players, make sure your teammates are ready to start. You can't add or remove team members after your session has started. Also note that *any* team member can start a session -- the continuous session timer starts when the final **Confirm** button is clicked.  
 
 ## Starting a challenge
 

docs/gameboard/practice-area.md

@@ -10,6 +10,8 @@ You can **search** for a challenge to practice on.
 
 You can copy a link to your search by selecting the **clipboard icon** next to the search field. In the example above, you may want to share the list of challenges/labs that have "firewall" content with another Gameboard user.
 
+Under *Need a place to start?* the Gameboard admin may have configured some suggested searches for participants. Players can select one of these tags to be directed to a set of available practice challenges. Gameboard admins should refer to "Suggested searches" in the [Admin Practice Area](admin-practice-area.md). 
+
 To start a practice session, select a challenge, then click **Start Practice Session**, and **Confirm**. You can only launch *one* practice challenge at a time. In the **Active Practice Challenge** screen, you can:
 
 - Extend your challenge session
@@ -22,11 +24,11 @@ To start a practice session, select a challenge, then click **Start Practice Ses
 
 In short, you get nearly the full competition challenge experience in the active practice session!
 
-Upon successfully solving the practice challenge, you can view a printable certificate commemorating your achievement...and you are returned to the Practice Area where you can select a new challenge to practice on.
+Upon successfully solving the practice challenge, you can view a printable certificate commemorating your achievement...and you are returned to the Practice Area where you can select a new practice challenge.
 
 !!! tip
 
-    You can view and print any certificate you earned in competition or in practice at any time from your profile screen. In the main navigation, click **Profile**. Then, select the **Practice** tab.
+    You can view and print any certificate you earned in competition or in practice at any time from your profile screen. In the main navigation, click **Profile**. Then, select the **Certificates** link.
 
 If your attempt to solve the practice challenge is *unsuccessful* (you've run out of time or used your allotted submissions), you can try the challenge again or return to the Practice Area to find another challenge. No certificates are awarded for partially completing a practice challenge.
 

docs/gameboard/reports-beta.md

@@ -1,17 +1,17 @@
-# Reports [BETA]
+# Reports
 
-As of v3.10.0, Gameboard features a beta version of an overhauled **Reports** module. The new beta Reports module is available to users who have `Admin`, `Registrar`, or `Support` roles in the main navigation bar.
-
-!!! note
-    The existing Reports functionality has not been deprecated; reports are still available under **Admin**, **Reports**, **User Reports**, **Board Reports**, etc. 
-
-Five report "cards" display the five reports available in beta:
+The **Reports** module is available to users who have `Admin`, `Registrar`, or `Support` roles in the main navigation bar. Six report "cards" display available reports:
 
 - **Challenges Report:** View information about the challenges configured in the Gameboard app. This report is good for site utilization metrics related to challenges, challenge deploys, and challenge solves.
 - **Enrollment Report:** View a summary of player enrollment data; who enrolled when, which sponsors do they represent, and how many played challenges.
 - **Players Report:** View data on player activity. A “player” is a person with an account on the Gameboard site (i.e., a "user").
 - **Practice Area Report:** View metrics on players who are spending free time honing their skills in Gameboard. See which challenges are practiced most, have the best success rates, and which players are accessing the Gameboard to complete challenges in practice.
-- **Support Report:** View a summary of support tickets created in Gameboard; including ticket creation and assignment details, ticket categories, and tickets attached to games/challenges .
+- **Site Usage Report:** View a high-level overview of user activity in the Gameboard. This report, optionally filtered by date range and sponsor, offers a digestible view of data related to players, sponsors, and challenges. Each statistic within the report contains a modal view for more detailed information. Note that the Site Usage Report can't be exported. 
+- **Support Report:** View a summary of support tickets created in Gameboard; including ticket creation and assignment details, ticket categories, and tickets attached to games/challenges.
+
+## Legacy Reports
+
+The legacy reporting functionality has not yet been deprecated; these reports are still available at the bottom of the Reports screen. Legacy reports won’t get future fixes or enhancements. Eventually, they will be removed from the Gameboard application.
 
 ## Common report characteristics
 
@@ -29,7 +29,7 @@ Each report shares common characteristics.
 
 ## Drilling down in results
 
-In some places in the report results, you can "drill down" by clicking a link in the metrics. A popup window displays a more granular view within the same data. For example: in the Enrollment Report, in the Performance category, some data points are links. See *screen print 1* below. Clicking that link goes deeper into that element. See *screen print 2* below.
+In some places in the report results, you can "drill down" by clicking a link in the metrics. A modal window displays a more granular view within the same data. For example: in the Enrollment Report, in the Performance category, some data points are links. See *screen print 1* below. Clicking that link goes deeper into that element. See *screen print 2* below.
 
 *Screen print 1: Summary Table*
 
@@ -90,11 +90,20 @@ The **Practice Area** report answers questions like these:
 4. How many users have deployed a practice challenge?
 5. How many different sponsors have deployed a practice challenge?
 
+## Site Usage Report
+
+The **Site Usage** report answers questions like these:
+
+1. How many players are active in the Gameboard in a given period of time?
+2. How many active players are associated with different sponsors?
+3. How many players are competitive players versus how many players are practice-only players?
+4. How many unique challenges versus how many total challenges were attempted in a given period of time?
+
 ## Support Report
 
 The **Support** report displays information about support tickets. Filter tickets by label, creation date and time, challenge, etc. The Support report answers questions like these:
 
 1. How many support tickets did we receive regarding the challenge titled "The Best Challenge"?
 2. How many tickets with a specific label did we receive?
 3. How many tickets did we receive on Tuesday?
-4. How many tickets did we receive during PC5 Teams Round 1?
+4. How many tickets did we receive during PC5 Teams Round 1?

docs/gameboard/support.md

@@ -1,4 +1,4 @@
-# Competition Support feature
+# Using the Integrated Support feature
 
 The gameboard platform comes with a built-in customer support interface so that competition hosts and administrators can assist competitors and players. This way, Gameboard is a "one-stop shop" and no outside apps or systems are required to track and measure issues reported by participants.
 
@@ -8,7 +8,7 @@ You must have either the `Support` role or `Admin` role to use the support featu
 
 ### Creating new support ticket
 
-From either of these locations <!--Once I see it in Launchpad, I can add more detail here-->, click **Create Ticket**. If you are coming from the challenge screen, then the Support Code, player id, and challenge id are automatically generated; if you are not, then this information can be added later.  
+You can create tickets from two places: the *Support* page or a challenge screen. In both cases you click the blue **Create Ticket** button to get started. If you are coming from the challenge screen, then the Support Code, player id, and challenge id are automatically generated; if you are not, then this information can be added later.  
 
 In the **Summary**, enter a brief statement of the problem.
 
@@ -23,23 +23,24 @@ After submitting the ticket, you can always **add a comment** and attach another
 ### Finding an existing ticket
 
 From the Support page, use the dropdowns and the **Search** field to locate existing tickets. Filter tickets by status:
-- Any and All
+
+- Any Status
 - Open
 - In progress
-- Not closed (*open* plus *in progress*)
+- Not Closed (*Open* plus *In Progress*)
 - Closed  
 
-Filter by assigned to you, unassigned, and assigned to anyone.
+Filter by *Assigned to me*, *Unassigned*, and *Any Assignment*. Finally, you can also *filter by labels*.
 
-Search by entering terms. Search covers ticket summary, labels, challenge titles, and player name. 
+Search by entering terms. Search covers ticket description, label, user, challenge title, and player.
 
 ## Support from the Support role point-of-view 
 
-Click the links at the top to instantly jump to challenge details, player details, and game details. <!--I'll add more detail here, too, when I can see and test.-->
+Click the links in the ticket header to instantly jump to the submitter's *Game* and *Challenge* details.
 
 ### Creating new support ticket
 
-The procedure for support role staff to create a tickets is very similar to procedure for participants to create a ticket (see above). However, after a ticket has been created users with the support staff role have more options to manage the tickets.  
+The procedure for support staff (i.e., users given the `Support` role) to create a tickets is very similar to procedure for participants to create a ticket (see above). However, after a ticket has been created users with the `Support` role have more options to manage the tickets.  
 
 ### Managing support tickets
 
@@ -61,10 +62,10 @@ From the Ticket management side-bar:
 
 Add a **comment** to communicate with the participant.
 
-### Copy ticket to markdown
+### Copy to markdown
 
-## Support-related Reporting
+The **Copy to markdown** icon allows you to copy support ticket content to Markdown. You can paste it anywhere, including into a messaging app or email, with nicely formatted text, avoiding the need for links or logins to the Gameboard.
 
-<!--This will change for sure. Just don't want to forget about writing this. If it is brief enough, I may include it in my Admin settings doc.-->
+## Support-related Reporting
 
-Some support-related reporting is provided in Gameboard to provide you with a way to track trends, manage workloads, and track trends during your competition. In the top-right corner, select **Admin**. Then click **Reports**, and **Support Reports**.
+Support-related reporting provides you with a way to manage workloads and track trends during your competition. In the main menu, select **Reports**. Then click **Support** in the Reports screen.

mkdocs.yml

@@ -40,7 +40,7 @@ markdown_extensions:
 # Page tree navigation
 nav:
 - Home: index.md
-- Identity guide:
+- Identity Guide:
   - About Identity: identity/index.md
   - Getting started with Identity: identity/getting-started.md
   - Logging in with user account: identity/user-account-login.md
@@ -49,7 +49,7 @@ nav:
   - Identity Profile: identity/profile.md
   - Identity Integration: identity/integration.md
   - Identity Accounts: identity/accounts.md
-- TopoMojo guide:
+- TopoMojo Guide:
   - About TopoMojo: topomojo/index.md
   - Getting started with TopoMojo: topomojo/getting-started.md
   - Finding an existing space: topomojo/finding-a-space.md
@@ -68,18 +68,16 @@ nav:
     - Users: topomojo/admin-users.md
     - Log: topomojo/admin-log.md    
   - Copy and paste: topomojo/copy-paste.md
-- Gameboard guide:
+- Gameboard Guide:
   - About the Gameboard: gameboard/index.md
-  - Getting started with Gameboard: gameboard/getting-started.md
   - Participating in a game: gameboard/participating.md
   - Practicing challenges: gameboard/practice-area.md
   - Using integrated support: gameboard/support.md
-  - Using Reports in beta: gameboard/reports-beta.md
+  - Using Reports: gameboard/reports-beta.md
   - Administering games: 
     - Administration: gameboard/admin.md
     - Practice: gameboard/admin-practice-area.md
     - Roles: gameboard/admin-roles.md
-    - Reports: gameboard/admin-reports.md
     - Players: gameboard/admin-players.md
     - Observe mode: gameboard/admin-observe.md
     - Settings: gameboard/admin-settings.md