Update User's Guide for 4.0.0

[georgemccabe]

I discovered some of the information in the User's Guide is out-of-date. This should be updated before the 4.0.0 release.

Describe the Task

Review and update User's Guide

Time Estimate

~1 day

Sub-Issues

Consider breaking the task down into sub-issues.

• Add a checkbox for each sub-issue here.

Relevant Deadlines

4.0.0

Funding Source

Define the source of funding and account keys here or state NONE.

Define the Metadata

Assignee

• Select engineer(s) or no engineer required
• Select scientist(s) or no scientist required

Labels

• Select component(s)
• Select priority
• Select requestor(s)

Projects and Milestone

• Review projects and select relevant Repository and Organization ones or add "alert:NEED PROJECT ASSIGNMENT" label
• Select milestone to next major version milestone or "Future Versions"

Define Related Issue(s)

Consider the impact to the other METplus components.

• METplus, MET, METdatadb, METviewer, METexpress, METcalcpy, METplotpy

Task Checklist

See the METplus Workflow for details.

• Complete the issue definition above, including the Time Estimate and Funding Source.
• Fork this repository or create a branch of develop.
  Branch name: feature_<Issue Number>_<Description>
• Complete the development and test your changes.
• Add/update log messages for easier debugging.
• Add/update unit tests.
• Add/update documentation.
• Push local changes to GitHub.
• Submit a pull request to merge into develop.
  Pull request: feature <Issue Number> <Description>
• Define the pull request metadata, as permissions allow.
  Select: Reviewer(s), Project(s), Milestone, and Linked issues
• Iterate until the reviewer(s) accept and merge your changes.
• Delete your fork or branch.
• Close this issue.

[j-opatz]

My review of Chapter 4 (Python Wrappers) revealed only one needed update:

GridStat

${METPLUS_OUTPUT_PREFIX needs an additional close bracket (${METPLUS_OUTPUT_PREFIX})

[jprestop]

I really like the changes you made and the new flow of Chapters 2/3.  I have a few suggestions.

I recommend changing the name of Chapter 2 from "Software Installation/Getting Started" to simply "Software Installation".  It'd be nice to have a shorter title and seem more accurate.  

I recommend adding bold to the words "bin" and "exec" and "share" in 3.2.1.1. MET_INSTALL_DIR for consistency.

I recommend adding italics to path locations in the following sections for consistency:
3.2.1.2. INPUT_BASE 
  parm/use_cases/model_applications
  and
  parm/use_cases/met_tool_wrapper

I noticed that references to OUTPUT_BASE are linked to in  3.2.2.2. METPLUS_CONF and 3.2.2.3. TMP_DIR, but not in 3.2.2.4. STAGING_DIR and thought maybe it should be a link there as well for consistency.

In section LOG_TIMESTAMP_TEMPLATE, I recommend adding a period between "20141231101159" and "Change" in the text below:
This example will use the format YYYYMMDDHHMMSS, i.e. 20141231101159 Change this value to adjust the frequency that new log files are created.

[georgemccabe]

My review of Chapter 4 (Python Wrappers) revealed only one needed update:

GridStat

${METPLUS_OUTPUT_PREFIX needs an additional close bracket (${METPLUS_OUTPUT_PREFIX})

I made this change in the branch.

[georgemccabe]

I really like the changes you made and the new flow of Chapters 2/3. I have a few suggestions.

I recommend changing the name of Chapter 2 from "Software Installation/Getting Started" to simply "Software Installation". It'd be nice to have a shorter title and seem more accurate.

I recommend adding bold to the words "bin" and "exec" and "share" in 3.2.1.1. MET_INSTALL_DIR for consistency.

I recommend adding italics to path locations in the following sections for consistency:
3.2.1.2. INPUT_BASE
parm/use_cases/model_applications
and
parm/use_cases/met_tool_wrapper

I noticed that references to OUTPUT_BASE are linked to in 3.2.2.2. METPLUS_CONF and 3.2.2.3. TMP_DIR, but not in 3.2.2.4. STAGING_DIR and thought maybe it should be a link there as well for consistency.

In section LOG_TIMESTAMP_TEMPLATE, I recommend adding a period between "20141231101159" and "Change" in the text below:
This example will use the format YYYYMMDDHHMMSS, i.e. 20141231101159 Change this value to adjust the frequency that new log files are created.

I agree with these suggestions and have made the changes in the branch.

[fisherhucar]

I did not see anything else needed changing for Chapter 4. Looks good.

[georgemccabe]

From email sent on 5/5/2021:

I assigned at least 1 scientist and 1 engineer to each section to review. Please review your section by the end of the week so we can make any edits before we create the release. Let me know if you are unable to review your section by then. There is also no penalty if you chose to review other sections as well!

Chapter 2 and 3 (Software Installation/Getting Started and System Configuration):

• John HG (@JohnHalleyGotway)
• Jonathan (@jvigh )
• Julie (@jprestop )

Chapter 4 (Python Wrappers):

• Hank (@fisherhucar )
• John O (@j-opatz )

Chapter 5

• Minna (@bikegeek )
• Dan (@DanielAdriaansen )

Comments can be added to the GitHub issue (this one) or if you prefer to make edits directly, make a branch off of the feature branch and provide the branch name in the GitHub issue.

Here is the link to the branch with the documentation updates:

https://metplus.readthedocs.io/en/feature_903_update_users_guide/Users_Guide/index.html

and the develop branch version for reference:

https://metplus.readthedocs.io/en/develop/Users_Guide/index.html

Most of the changes are in Chapters 2-4. There was a lot of duplicate information in Chapters 2 and 3, so I did my best to rearrange the content so it flows better and the content is relevant to each section. I think there was a lot of duplicate content because we split up writing the chapters and we didn't come up with a consensus for which sections to include which content, so I think it would be good for Chapters 2 and 3 to be reviewed together by the same person.

[jvigh]

Hi George, I am unclear as to the timeline for this. Was it needed by last Friday, or this coming Friday (May 15)? I am in a conference all week, but if it's needed right away, I can try to work on this later this afternoon. Jonathan Jonathan Vigh Project Scientist I, Joint Numerical Testbed Research Applications Laboratory (RAL) National Center for Atmospheric Research (NCAR) P.O. Box 3000 tel: +1 (303) 497-8205 Boulder, CO 80307-3000 fax: +1 (303) 497-8171Jonathan's Staff Web Page <http://www.ral.ucar.edu/staff/jvigh/> (CV, publications, etc.)Tropical Cyclone Guidance Project <http://hurricanes.ral.ucar.edu/> (real-time hurricane data) Tropical Cyclone Data Project <https://verif.rap.ucar.edu/tcdata/> (FLIGHT+, VDM+, TC-OBS datasets) Hurricane Risk Calculator <https://wxrisk.ucar.edu> (personalizing hurricane risk assessments for evacuation decision support) During COVID-19, my working day is definitely not the same as your working day. Please do not feel obliged to reply to this email outside of your normal working hours.

…

On Mon, May 10, 2021 at 9:25 AM George McCabe ***@***.***> wrote: From email sent on 5/5/2021: I assigned at least 1 scientist and 1 engineer to each section to review. Please review your section by the end of the week so we can make any edits before we create the release. Let me know if you are unable to review your section by then. There is also no penalty if you chose to review other sections as well! Chapter 2 and 3 (Software Installation/Getting Started and System Configuration): - John HG ***@***.*** <https://github.com/JohnHalleyGotway>) - Jonathan ***@***.*** <https://github.com/jvigh> ) - Julie ***@***.*** <https://github.com/jprestop> ) Chapter 4 (Python Wrappers): - Hank ***@***.*** <https://github.com/fisherhucar> ) - John O ***@***.*** <https://github.com/j-opatz> ) Chapter 5 - Minna ***@***.*** <https://github.com/bikegeek> ) - Dan ***@***.*** <https://github.com/DanielAdriaansen> ) Comments can be added to the GitHub issue (this one) or if you prefer to make edits directly, make a branch off of the feature branch and provide the branch name in the GitHub issue. Here is the link to the branch with the documentation updates: https://metplus.readthedocs.io/en/feature_903_update_users_guide/Users_Guide/index.html and the develop branch version for reference: https://metplus.readthedocs.io/en/develop/Users_Guide/index.html Most of the changes are in Chapters 2-4. There was a lot of duplicate information in Chapters 2 and 3, so I did my best to rearrange the content so it flows better and the content is relevant to each section. I think there was a lot of duplicate content because we split up writing the chapters and we didn't come up with a consensus for which sections to include which content, so I think it would be good for Chapters 2 and 3 to be reviewed together by the same person. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#903 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEWD6VXWIEZPUJ5UWDEVADDTM73HXANCNFSM44BQ6ALQ> .

[georgemccabe]

@jvigh the release is scheduled for this afternoon, so any documentation updates should be in before then if they will be included in the release.

[jvigh]

My conference session ends today at 2 PM. I can start reviewing it then if it's still needed. Have you had any reviews yet for those Chapters? Jonathan Vigh Project Scientist I, Joint Numerical Testbed Research Applications Laboratory (RAL) National Center for Atmospheric Research (NCAR) P.O. Box 3000 tel: +1 (303) 497-8205 Boulder, CO 80307-3000 fax: +1 (303) 497-8171Jonathan's Staff Web Page <http://www.ral.ucar.edu/staff/jvigh/> (CV, publications, etc.)Tropical Cyclone Guidance Project <http://hurricanes.ral.ucar.edu/> (real-time hurricane data) Tropical Cyclone Data Project <https://verif.rap.ucar.edu/tcdata/> (FLIGHT+, VDM+, TC-OBS datasets) Hurricane Risk Calculator <https://wxrisk.ucar.edu> (personalizing hurricane risk assessments for evacuation decision support) During COVID-19, my working day is definitely not the same as your working day. Please do not feel obliged to reply to this email outside of your normal working hours.

…

On Mon, May 10, 2021 at 10:27 AM George McCabe ***@***.***> wrote: @jvigh <https://github.com/jvigh> the release is scheduled for this afternoon, so any documentation updates should be in before then if they will be included in the release. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#903 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEWD6VREWDZ55EP2TN5AXELTNACOJANCNFSM44BQ6ALQ> .

[DanielAdriaansen]

I don't have any changes or suggestions for chapter 5 for this release. I looked at some of the newer use cases that were added for this release but didn't review every single use case page since much of those were touched and reviewed as part of the work in #768. Chapter 5 looks good to go.

[JohnHalleyGotway]

@georgemccabe and @jprestop I just pushed a couple of user's guide edits. Please see my commits here:
b004766

Do these changes look OK to you?

[jvigh]

Hi George,
I have finished reviewing the METplus UG, Ch. 2. Most of the changes are minor, however there are a few places where I think it helps to be a bit more prescriptive to the user as to what they need to do. I've highlighted these using suggesting mode in the following Google doc. I'll work on Chapter 3 next.

https://docs.google.com/document/d/16pr8EdFKC01RaqIXZ-lcjCUjaMhTo8Sf_u3TF9lEKDQ/edit#

Jonathan

[jvigh]

Update: I'm down to section 3.2.3 so far. No changes to suggest yet.