Standardize information to live in ARGS_SPEC about text vs the User's Guide

[phargogh]

We started an interesting discussion over in #895 about the amount of information that should live in the ARGS_SPEC about text. In Seasonal Water Yield, there are several inputs where files are expected to have filenames matching a pattern that identifies the month the file represents (e.g. precip or ET0 for January). How much information should be in the about text vs in the user's guide?

Once we arrive at a decision about this, it might be useful to add to the InVEST spec.

[emlys]

Back when I deduplicated all the ARGS_SPEC and user's guide content in order to implement the custom sphinx role (PRs natcap/invest.users-guide#42, natcap/invest.users-guide#45, natcap/invest.users-guide#47, #604, #633, #639) I merged the arg description content following these guidelines:

• the ARGS_SPEC should have the minimum amount of information that the user needs to provide a correct input
• the about text should not duplicate anything that's stored in another spec property (units, projection, etc)
  • except for args that are conditionally required. These should have a sentence explaining when they are required (e.g. "Required if Run Valuation is selected.")
• the user's guide can have any other info that we want to provide, such as
  • examples of what the input should look like
  • how to choose a value for the input (from a scientific perspective)
  • where to find data for the input

The goal was to keep the spec as short as possible and leave the user's guide open for any other info. My reasoning was

• Because we're combining the spec with the user's guide to generate the docs, we need a clear definition of what goes where. Having "the minimum" in one and "everything else" in the other is easier to define and follow than a more nuanced split.
• Folks outside the software team can edit the user's guide, but not the spec very easily. Keeping more text in the user's guide means that it's more accessible to them (and less work for us to keep up with minor revisions).
• Text in the spec can't be formatted, but text in the user's guide can be formatted with the full range of RST options. We might want to format things like example file names: evapotranspiration_1.tif or evapotranspiration_1.tif, but that can't be done in the spec.
• Current use cases for the about text are: (1) tooltip text in the UI and (2) quick reference for us when reading the model code. Keeping it brief makes sense for both those purposes.

These guidelines are opinionated but I'm sure we discussed it when I worked on those PRs. Happy to discuss further - maybe changes to the about text/UG split are warranted now that we've seen what this first implementation is like. And we're bound to have different ideas about what the "minimum necessary information" is so that would be good to clarify.