Merge pull request #567 from NASA-IMPACT/update_guides

Update guides

content/help-documentation/apt.md

@@ -32,7 +32,7 @@ Data users have often found searching for and discovering existing ATBDs very ch
 
 [[Back to top](#)]
 
-## 2. Details of the Algorithm Publicatin Tool Pages and Features
+## 2. Details of the Algorithm Publication Tool Pages and Features
 
 APT has various features that improve the process of authoring, searching, and discovering documents and content through the centralized ATBD repository.
 
@@ -85,7 +85,7 @@ A user will be redirected to your user dashboard when you successfully log into
 1. **Dashboard** – This button redirects you to your individual dashboard containing all documents associated with your account, if they are an approved user (Figures 6-9). If you are not an approved user, you will see only the public ATBDs on the dashboard.
 2. **Contacts** – This button redirects you to the Contacts page which lists all contacts stored within APT and allows you to create a new contact (see Section 2.2.1).
 3. **About** – This button redirects you to the About page, which introduces APT.
-4. **User Guide** – This button redirects you to this document, the APT user guide (see Section 2.2.2).
+4. **User Guide** - This button redirects you to this document, the APT user guides (see Section 2.2.2). 
 5. **Feedback** – This button brings up a form for you to submit feedback about APT to the project team (see Figure 3).
 6. **Username and profile** – The username of the current account appears in the upper right once you successfully log in to APT. The dropdown menu provides two options; view your profile or sign out of your APT account. If signing out, you are automatically redirected to the public APT dashboard.
 
@@ -166,7 +166,7 @@ Users can create a new ATBD or edit an existing one (Figure 13) from the user da
 ![Figure 14b](https://github.com/bwbaker1/APT_UserGuide_Figures/blob/main/APT_Figure14b.png?raw=true "Figure 14b. Prompt that appears when a user creates a new ATBD. Users must indicate whether they want to create a document within the APT interface or to upload an existing ATBD PDF.")
 
 1. **Title** – Authors should enter a descriptive, formal title of the ATBD. It is recommended that the title be as descriptive as possible, while keeping acronyms to a minimum.
-2. **Alias** – Authors should enter an alias title for the ATBD. Once an ATBD is completed, the alias will not be editable.
+2. **Alias** – Authors should enter an alias title for the ATBD. Once an ATBD is completed, the alias will not be editable. All aliases should be unique.
 3. **Create new ATBD in APT** – Select to create an ATBD within the APT interface.
 4. **Upload existing ATBD PDF** – Select to upload an existing ATBD PDF that was created using one of the provided ATBD templates.
 
@@ -197,7 +197,7 @@ The first authoring step prompts a user to input unique information that identif
 1. **Comments** – Clicking this button opens the comments section of the ATBD (Figure 18b). A user can add or respond to a comment by clicking this icon anywhere it is found in APT.
 2. **Information** – Clicking this icon reveals more information that can be helpful with understanding the needed content for the text field. This is a persistent feature within APT that operates in the same way anywhere a user finds it located.
 3. **Title** – Authors should enter a descriptive, formal title of the ATBD. It is recommended that the title be as descriptive as possible, while keeping acronyms to a minimum.
-4. **Alias** – Authors should enter an alias title for the ATBD. Once an ATBD is completed, the alias will not be editable.
+4. **Alias** – Authors should enter an alias title for the ATBD. Once an ATBD is completed, the alias will not be editable. All alias must be unique.
 5. **DOI** – Enter the digital object identifier (DOI) associated with this ATBD. The DOI is assigned by the APT curator.
 6. **Section progress** – Toggle feature that allows authors to mark the section as complete or incomplete. This is a persistent feature through each step.
 7. **Version description** – Author should provide a meaningful description of how this APT ATBD version differs from previous versions. This is only important for new major versions of the ATBD.
@@ -219,10 +219,12 @@ The first authoring step prompts a user to input unique information that identif
 
 [[Back to top](#)]
 
-#### 2.3.2 Contact Information (Step 2)
+#### 2.3.2 Contact and Reviewer Information (Step 2)
 
 The second step requests contact information for the individual or group responsible for fielding user questions regarding the ATBD (Figure 20). APT stores information from all published documents, which authors can retrieve and use in other documents. Therefore, authors have the option to search for existing contact information stored in APT and should use this information whenever possible instead of entering information manually. This ensures that information is consistent across all documents, which is an advantage of APT.
 
+Document reviewers should be added as a contact. However, their information will not be included on the document PDF. Select “Document Reviewer” under roles related to the document. A minimum of two reviewers are required. 
+
 ![Figure 20](https://github.com/bwbaker1/APT_UserGuide_Figures/blob/main/APT_Figure20.png?raw=true "Figure 20. Individual or group contact information. The red outlined and labeled items correspond to the numbered descriptions in text below.")
 
 1. **Add a contact** – This feature allows authors to add ATBD contact information. Once selected, users have the option to search for an existing contact or create a new contact (Figure 28).
@@ -312,8 +314,8 @@ This step first describes the scientific and mathematical theories and assumptio
 
 ![Figure 28](https://github.com/bwbaker1/APT_UserGuide_Figures/blob/main/APT_Figure28.png?raw=true "Figure 28. Insert the mathematical theory and assumptions associated with the algorithm. The red outlined and labeled items correspond to the numbered descriptions in text below.")
 
-1. **Describe the mathematical theory** – Describe the mathematical theory that is essential to the algorithm’s development.
-2. **Mathematical theory assumptions** – Provide a description of any mathematical assumptions, simplifications, and approximations made when deriving the algorithm.
+1. **Describe the mathematical theory** – Describe the mathematical theory that is essential to the algorithm’s development. Mathematical theory is not required; however, the section is required. If there is no mathematical theory to add, please write “see scientific theory above.”
+2. **Mathematical theory assumptions** – Provide a description of any mathematical assumptions, simplifications, and approximations made when deriving the algorithm. If there are retrieval error uncertainties, add a new header within the mathematical theory section.
 
 ![Figure 29](https://github.com/bwbaker1/APT_UserGuide_Figures/blob/main/APT_Figure29.png?raw=true "Figure 29. Add input and output variables used and generated by the algorithm. The red outlined and labeled items correspond to the numbered descriptions in text below.")
 

content/help-documentation/quickstart.md

@@ -75,7 +75,7 @@ Use APT authoring environment
 
 - Give your ATBD a title. Continue adding content (see the [User Guide](https://www.earthdata.nasa.gov/apt/user-guide) for more details). See section 2.3 to learn how to add collaborators.
 
-![Figure 9](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure9_ATBD_Title.png?raw=true 'Figure 9. Give your ATBD a title')
+![Figure 9](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_FIgure_ATBD_Title.png?raw=true 'Figure 9. Give your ATBD a title')
 
 Use provided ATBD template
 
@@ -93,7 +93,7 @@ Use provided ATBD template
 - Navigate to the Attachment step and click choose a file to upload. Locate your PDF and click “open.” Then click “save” (Figure 12).
 - Click “view selected file” to view your uploaded ATBD (Figure 13).
 
-![Figure 10](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure10_trigger_PDF.png?raw=true 'Figure 10. Click the toggle to indicate that you have an existing ATBD PDF to submit')
+![Figure 10](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure10_trigger_PDF.png?raw=true 'Figure 10. Enter the title of your ATBD and click "Create new ATBD in APT" or "Upload existing ATBD PDF".')
 
 ![Figure 11](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure11_PDF_Upload.png?raw=true 'Figure 11. Enter the information related to your ATBD in the identifying information step')
 
@@ -117,7 +117,11 @@ Most ATBDs are a collaborative effort; therefore, multiple authors can be added
 
 ### 2.4 How to Suggest a Reviewer for Your ATBD
 
-Coming soon.
+At least two people are required to review the ATBD. Reviewer information will not appear on the document PDF, but will appear on the HTML page (i.e., landing page once published). The APT curator will use this information to contact and get the reviewers set-up on the document. 
+
+![Figure 17](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure17_AddReviewer.png?raw=true 'Figure 17. Select the role as "Document Reviewer" if the contact is or will review the document.')
+
+Add the reviewer’s information within the “Contact and Reviewer” section. Select “Document Reviewer” as their role related to the document. At least two reviewers are required. 
 
 [[Back to top](#)]
 
@@ -129,9 +133,9 @@ An ATBD is typically developed in APT over time. Since one can work on any secti
 - Click “save.” A message letting you know that your document has been saved will appear. If this message does not appear, your document has not been saved.
 - You can then see the progress in the section drop-down list (Figure 18).
 
-![Figure 17](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure17_sectionprogress.png?raw=true 'Figure 17. The section or subsection box can be marked complete when finished by selecting the appropriate status shown in the red box.')
+![Figure 18](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure17_sectionprogress.png?raw=true 'Figure 18. The section or subsection box can be marked complete when finished by selecting the appropriate status shown in the red box.')
 
-![Figure 18](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure18_sectionprogress2.png?raw=true 'Figure 18. Check progress via the dropdown at the upper right of the blue bar (red box). This example shows the algorithm description section is 25% complete.')
+![Figure 19](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure18_sectionprogress2.png?raw=true 'Figure 19. Check progress via the dropdown at the upper right of the blue bar (red box). This example shows the algorithm description section is 25% complete.')
 
 [[Back to top](#)]
 
@@ -155,15 +159,15 @@ Prior to review, the author(s) will provide the curator with the names and email
 
 Upon your next login, click the reviewer tab to see ATBDs that your user role is a reviewer (Figure 19). You can view the document in HTML or download it as a PDF (Figure 20). As you review the document, provide feedback and notes to authors by leaving comments. Adding comments is discussed in section 3.1.
 
-![Figure 19](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_FIgure19_ReviewTab.png?raw=true 'Figure 19. From the user dashboard, navigating to the Reviews tab (red box) will display all documents where your role is reviewer.')
+![Figure 20](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_FIgure19_ReviewTab.png?raw=true 'Figure 20. From the user dashboard, navigating to the Reviews tab (red box) will display all documents where your role is reviewer.')
 
-![Figure 20](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure20_ReviewDownloadPDF.png?raw=true 'Figure 20. Clicking on the document from the review tab will open it up in HTML mode. A PDF of the document can be downloaded by clicking on Download (red box).')
+![Figure 21](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure20_ReviewDownloadPDF.png?raw=true 'Figure 21. Clicking on the document from the review tab will open it up in HTML mode. A PDF of the document can be downloaded by clicking on Download (red box).')
 
 Click “conclude review” once you are finished with your review (Figure 21), and then click confirm (Figure 22). The curator will transition the document to open review after all of the reviewers have concluded their review. The document is editable again in open review. In open review, the authors and reviewers work iteratively to address any issues. Once the authors and reviewers are satisfied and all comments are marked as resolved, the lead author has the option to request that the document be published.
 
-![Figure 21](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure21_ConcludeReview.png?raw=true "Figure 21. A review is completed by clicking 'conclude review' (red box)")
+![Figure 22](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure21_ConcludeReview.png?raw=true "Figure 22. A review is completed by clicking 'conclude review' (red box)")
 
-![Figure 22](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure22_ConfirmReview.png?raw=true 'Figure 22. Confirm (red box) that you have concluded your review.')
+![Figure 23](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure22_ConfirmReview.png?raw=true 'Figure 23. Confirm (red box) that you have concluded your review.')
 
 [[Back to top](#)]
 
@@ -175,12 +179,12 @@ Comments can be added to specific sections of the ATBD and specific users can be
 
 Existing comments can be replied to and resolved (Figure 25). A user can also edit and delete their own comments but not other users' comments (Figure 26).
 
-![Figure 23](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure23_CommentsIcons.png?raw=true 'Figure 23. Comment threads are opened by clicking the comments icon on the page banner (red box).')
+![Figure 24](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure23_CommentsIcons.png?raw=true 'Figure 24. Comment threads are opened by clicking the comments icon on the page banner (red box).')
 
-![Figure 24](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure24_Comments.png?raw=true 'Figure 24. Comment threads. Use the comment under the general dropdown to select which section to add the comment and use the notify users dropdown to select which users to notify of regarding the comment (red box).')
+![Figure 25](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure24_Comments.png?raw=true 'Figure 25. Comment threads. Use the comment under the general dropdown to select which section to add the comment and use the notify users dropdown to select which users to notify of regarding the comment (red box).')
 
-![Figure 25](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure25_CommentResolve.png?raw=true 'Figure 25. Reply to comments using the reply to comment icon and resolve comment threads using the resolve comment thread icon (red box).')
+![Figure 26](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure25_CommentResolve.png?raw=true 'Figure 26. Reply to comments using the reply to comment icon and resolve comment threads using the resolve comment thread icon (red box).')
 
-![Figure 26](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure26_CommentEdit.png?raw=true 'Figure 26. A user can edit or delete their own comment from the options dropdown menu (red box).')
+![Figure 27](https://github.com/bwbaker1/APT_QuickStart_Figures/blob/main/QS_Figure26_CommentEdit.png?raw=true 'Figure 27. A user can edit or delete their own comment from the options dropdown menu (red box).')
 
 [[Back to top](#)]