docs: Add User Guide (#2121)

docs/.vitepress/config.mts

@@ -1,62 +1,106 @@
-import { defineConfig } from 'vitepress';
-import { SearchPlugin } from 'vitepress-plugin-search';
+import { defineConfig } from "vitepress";
+import { SearchPlugin } from "vitepress-plugin-search";
 
 var options = {
-  previewLength: 62,
-  buttonLabel: "Search",
-  placeholder: "Search docs",
-  allow: [],
-  ignore: [],
+    previewLength: 62,
+    buttonLabel: "Search",
+    placeholder: "Search docs",
+    allow: [],
+    ignore: [],
 };
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  vite: { plugins: [SearchPlugin(options)]},
-  title: "Pilcrow Documentation",
-  description: "Documentation site for pilcrow.dev",
-  themeConfig: {
-    // https://vitepress.dev/reference/default-theme-config
-    editLink: {
-      pattern: 'https://github.com/mesh-research/pilcrow/edit/master/docs/:path'
-    },
-    nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Installation', link: '/install/' },
-      { text: "Developers", link: '/developers/' }
-    ],
-
-    sidebar: {
-      '/developers/': [{
-        text: 'Developers',
-        items: [
-          { text: 'Introduction', link: '/developers/' },
-          { text: "Getting Started", link: '/developers/getting-started' },
-          { text: "Team", link: '/developers/team' },
-          { text: 'Architecture', link: '/developers/architecture' },
-          { text: 'Testing', link: '/developers/testing' },
-          { text: 'Copyediting', link: '/developers/copyediting' },
-          { text: 'Documentation', link: '/developers/documentation' },
-          { text: 'Staging Environments', link: '/developers/staging' }
-        ]
-      }],
-      "/install/": [{
-          items: [
+    vite: { plugins: [SearchPlugin(options)] },
+    title: "Pilcrow Documentation",
+    description: "Documentation site for pilcrow.dev",
+    themeConfig: {
+        // https://vitepress.dev/reference/default-theme-config
+        editLink: {
+            pattern:
+                "https://github.com/mesh-research/pilcrow/edit/master/docs/:path",
+        },
+        nav: [
+            { text: "Home", link: "/" },
+            { text: "Guide", link: "/guide/" },
             { text: "Installation", link: "/install/" },
-            { text: "Configuration", link: "/install/config"},
-            {
-              text: "Recipes", items: [
-                { text: "Mysql", link: "/install/recipes/mysql" },
-                { text: "SSL/Reverse Proxy", link: "/install/recipes/proxy" },
-                { text: "Redis", link: "/install/recipes/redis" }
+            { text: "Developers", link: "/developers/" },
+        ],
 
-            ]}
-          ]
-      }]
+        sidebar: {
+            "/guide/": [
+                {
+                    text: "Guide",
+                    items: [
+                        { text: "Introduction", link: "/guide/" },
+                        { text: "Reviewing", link: "/guide/reviewing" },
+                        { text: "Notifications", link: "/guide/notifications" },
+                        { text: "Contact", link: "/guide/contact" },
+                    ],
+                },
+            ],
+            "/developers/": [
+                {
+                    text: "Developers",
+                    items: [
+                        { text: "Introduction", link: "/developers/" },
+                        {
+                            text: "Getting Started",
+                            link: "/developers/getting-started",
+                        },
+                        { text: "Team", link: "/developers/team" },
+                        {
+                            text: "Architecture",
+                            link: "/developers/architecture",
+                        },
+                        { text: "Testing", link: "/developers/testing" },
+                        {
+                            text: "Copyediting",
+                            link: "/developers/copyediting",
+                        },
+                        {
+                            text: "Documentation",
+                            link: "/developers/documentation",
+                        },
+                        {
+                            text: "Staging Environments",
+                            link: "/developers/staging",
+                        },
+                    ],
+                },
+            ],
+            "/install/": [
+                {
+                    items: [
+                        { text: "Installation", link: "/install/" },
+                        { text: "Configuration", link: "/install/config" },
+                        {
+                            text: "Recipes",
+                            items: [
+                                {
+                                    text: "Mysql",
+                                    link: "/install/recipes/mysql",
+                                },
+                                {
+                                    text: "SSL/Reverse Proxy",
+                                    link: "/install/recipes/proxy",
+                                },
+                                {
+                                    text: "Redis",
+                                    link: "/install/recipes/redis",
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        },
 
+        socialLinks: [
+            {
+                icon: "github",
+                link: "https://github.com/mesh-research/pilcrow",
+            },
+        ],
     },
-
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/mesh-research/pilcrow' }
-    ]
-  }
-})
+});

docs/guide/contact.md

@@ -0,0 +1,14 @@
+# Contact
+
+## Development Team
+
+You can contact the development team in the following ways to report bugs or provide feedback and feature requests about how Pilcrow functions. Use whatever method is most comfortable for you:
+
+### Feature Requests Site
+
+* <https://feedback.pilcrow.dev/>
+
+### GitHub
+
+* Issues - <https://github.com/MESH-Research/Pilcrow/issues>
+* Discussions - <https://github.com/MESH-Research/Pilcrow/discussions>

docs/guide/index.md

@@ -0,0 +1,21 @@
+# Guide
+
+## Registration
+
+You must register as a user on the platform before you can submit or review for the first time. To register go to the Pilcrow submission portal and choose the register link from the upper right corner of the page. If enabled, you may be able to register using an external identity provider like ORCID or Google so you can use your ORCID or Google account to authenticate. You will be asked for your name and email and to create a username. If you aren’t registering using an ORCID or Google account, you will also be asked to create a password. Once you are done with this, click the “Create Account” button.
+
+You will be immediately logged into the system and you will see a yellow banner across the top that lets you know you need to verify your email by going to your email and clicking a link. You can resend the email if you don't get it. There may be delays with this email being sent. Be sure to check your junk mail because the email is sometimes filtered out.
+
+The email will be titled “Verify Email Address,” and will come from the name of the Pilcrow instance you are registering for in the email. It will contain a button titled, “Verify Email Address.” Clicking this will verify your email and take you to the Pilcrow instance where you will see a success message and a button to visit the Dashboard page.
+
+## Logging In
+
+Once you have an account you can return to Pilcrow at any time and use the Login button to log in. If you ever forget your password you can reset it by pressing the reset password link on the login page, and by entering the email address you used to set up your account.
+
+You will see a confirmation message when you press the submit button after entering your email address. Next, check your email. The email will come from the name of the Pilcrow instance you are registering for and will be titled Reset Password Notification. Inside the email, you will see a button titled “Reset Password.” Pressing this button will take you to the Pilcrow instance with a prompt to enter your new password. Once you have submitted your new password you’ll see a confirmation that the password has been reset and a button to return to the dashboard.
+
+Note that the password reset link must be used within 60 minutes of requesting a password reset or you will have to start the process again.
+
+## Profile
+
+One of the first things you can do when you log in to Pilcrow is update your profile. In the upper right corner of the page click the arrow button next to your username. This will load the standard profile that will only be populated with your username and name. You can fill out as many or as few fields on this page as you wish. Once you have made the changes scroll to the bottom of the page and you will see a purple “SAVE” button to save them. If you press a button to navigate away from the page before you have saved it, the system will prompt you to discard the changes or to keep them.

docs/guide/notifications.md

@@ -0,0 +1,7 @@
+# Notifications
+
+There are two different types of notifications in Pilcrow: in-app and email. As a user, you will receive notifications for different activities that take place depending upon your role relative to the activities.
+
+For example, if you’re a reviewer of a submission, you will be notified whenever someone changes the status of the submission you’re reviewing. The user changing the status of the submission will have the opportunity to provide an optional comment. This optional comment will be included in this activity’s email notification. This optional comment will also appear within the Activity section at the bottom of the submission’s Details page.
+
+Not all activities will trigger a notification, as the development team considers this an ongoing project and is still developing notifications. If you’d like to suggest to the development team that a notification be triggered for a particular activity, feel free to contact the development team to do so.

docs/guide/reviewing.md

@@ -0,0 +1,45 @@
+# Reviewing
+
+## Find a Document You Are Assigned
+
+Once you have successfully registered for the platform you can be assigned to review a paper by the Editor or Review Coordinator of the publication you are working with.
+
+When you log into the system you should see any submissions you are assigned to showing up in the Reviews table on your Dashboard. If you do not see anything there or prefer to see a different view you can choose the “Reviews” tab at the top of the page in the menu bar.
+
+To review the submission you can either click on the Submission Title in the table, or you can click on the three vertical dots under “Actions” on the right side of the table and choose “Review”
+
+Also from the Actions table, you can choose to visit the Submission Details page which provides detailed information about the submission including who is assigned to it, and any activity associated with the submission.
+
+Note: you can also access the Submission Details page when you are reviewing the submission by clicking on the arrow facing left in the upper left corner of the document next to the title and the status indicator.
+
+## Submission Details Page
+
+The Submission Details page provides detailed information about the submission including who is assigned to it and any activity associated with the submission.
+
+From this page, you can find email addresses for the submitter, review coordinator, and fellow reviewers. You can also see the Activity log for the submission which includes when the status of the document has been changed and any comments associated with the change of status from the user who changed it.
+
+## The Review Page
+
+When you open a submission to the review page you will see the submission content on the left side of the screen, the Overall Comments section beneath the submission content, and the Inline Comments on the right. Above the submission text are controls for font, font size, dark mode, and shortcuts to the Overall Comments section. The secondary navigation bar above it gives the title of the submission, the status of the submission, and a button on the left to return to the Submission Details page, as well as the buttons on the right side to toggle whether or not inline comments and their highlights are shown.
+
+### Document and Controls
+
+Because digital documents do not require page numbering the Pilcrow system uses paragraph numbering to allow reviewers and authors to identify and reference portions of the document. You will see a pilcrow symbol followed by the paragraph number to the left of the first sentence of any given paragraph.
+Pilcrow also has some built-in accessibility features to help with your ability to make modifications to the visual display of the submission.
+
+* light/dark mode is provided to allow you to switch between a light or dark background
+* text size and font allows you to change the fonts and size of the text in the document as you review it.
+
+## How to make an inline comment
+
+To make an inline comment in Pilcrow find the area of the document that you wish to comment on and highlight it. Once you have highlighted a word, sentence, paragraph, or area you wish to comment on you can press the plus button that shows up above the highlighted area to open the inline comment form. This form features an area to write your comment along with minimal formatting options, and then the ability to tag the comment with any or all of the review criteria identified by the publication you are working in. To tag your comment with a particular criterion, use the switch button to the right of the criteria you wish to tag.  once you have made your comment and tagged it appropriately press the submit button to add the comment.
+
+To reply to an existing one, use the purple reply button under the comment to open the reply area. This looks much like the form for inline comments. Once you have made your comment reply you can press Submit to add it to the comment thread.
+
+When there are one or more replies to a comment in the Inline Comments section you will see that the purple “Reply” button changes to one that is dark blue and labeled, “Show Replies.” You will see all replies associated with the original inline comment by clicking on this button. You can also add a comment reply of your own to any of the replies by clicking on the triple dot menu for the comment you’d like to reply to and selecting “Quote Reply.” Each comment or reply will show how long ago it was made.
+
+## How to make an overall comment
+
+You can add overall comments to the submission by scrolling to the bottom of the submission. You also can click the small grey plus that is near the “light mode” text at the top of the document to be taken to the Overall Comments section at the bottom. This can be helpful if the document is long.
+
+Once at the bottom of the page, you can use the Overall Comments box to add additional comments that pertain to the submission as a whole and/or engage in conversation with the author and other reviewers about the submission more broadly. The Overall Comments area functions the same way other comments do, with the ability to enter your comments and then press submit once you are finished.

docs/index.md

@@ -10,6 +10,9 @@ hero:
   tagline: "Collaborative Community Review"
   actions:
     - theme: brand
+      text: Guide
+      link: /guide/
+    - theme: alt
       text: Installation
       link: /install/
     - theme: alt