Documentation type
Installation or setup guide
Type of issue
Incomplete — documentation is missing key information
Location
No response
What is wrong or missing?
The installation workflow is more complex than it needs to be,
- some commands are slow
- or unclear, and
- error messages do not give enough information.
Issues Identified
- Conda installation is too slow. Add optional installation commands using Mamba for users who have Mamba available.
Document the Mamba commands alongside the Conda commands as a faster alternative.
- Simplify the configuration and first-run workflow
Currently, users need to explicitly create/configure a configuration file before running Adapt. This adds unnecessary steps for a first-time demo.
Proposed behavior:
If: config.yaml does not exist, and
the user did not provide another configuration file,
then Adapt should: Create a default config.yaml.
Start the run directly when the user executes run-nexrad.
This would reduce the number of steps between installation and actually running Adapt.
- Pydantic validation errors show raw error output that is difficult for users to understand.
Proposed improvement:
Catch configuration/Pydantic validation errors.
Convert them into descriptive, user-facing error messages.
Clearly explain:
what is wrong,
which configuration field caused the problem,
what value or format is expected, and
what the user should do next.
The goal should be that a user can resolve common configuration problems without needing to understand Pydantic internals or search through the source code.
- Improve feedback after Adapt starts
When Adapt successfully runs, the CLI should provide more useful information about what just happened.
For example, after a successful run, Adapt could tell the user:
what Adapt did,
which configuration was used,
where outputs were created,
what the user can try next, and
which commands/options are available for exploring other workflows.
This would help users discover Adapt's capabilities.
- Document how to create the working directory
The current documentation does not ask to create the directory dor data.
The terminology is also important. We should consistently call this a working directory rather than a "repository." Calling it a repository can confuse users thinking a GitHub repository.
- Reconsider the overall installation workflow
The current workflow has too many steps for a new user:
Install → create directory → configure → create config → run
We should aim for a simpler first-run experience, ideally closer to:
Install → create working directory → run-nexrad
with Adapt creating a sensible default configuration automatically when needed.
Suggested correction or addition
For the current release, we should improve the documentation to make the existing workflow as clear as possible.
For a future release, we should revisit the overall CLI and installation design to determine how the workflow can be presented more simply and intuitively.
Acceptance Criteria
Future Work
For a future release, we should consider a broader redesign of the installation and first-run experience rather than continuing to add instructions around a complex workflow. The goal should be to make the path from a fresh installation to a useful Adapt run as short, discoverable, and self-explanatory as possible.
Documentation type
Installation or setup guide
Type of issue
Incomplete — documentation is missing key information
Location
No response
What is wrong or missing?
The installation workflow is more complex than it needs to be,
Issues Identified
Document the Mamba commands alongside the Conda commands as a faster alternative.
Currently, users need to explicitly create/configure a configuration file before running Adapt. This adds unnecessary steps for a first-time demo.
Proposed behavior:
If: config.yaml does not exist, and
the user did not provide another configuration file,
then Adapt should: Create a default config.yaml.
Start the run directly when the user executes run-nexrad.
This would reduce the number of steps between installation and actually running Adapt.
Proposed improvement:
Catch configuration/Pydantic validation errors.
Convert them into descriptive, user-facing error messages.
Clearly explain:
what is wrong,
which configuration field caused the problem,
what value or format is expected, and
what the user should do next.
The goal should be that a user can resolve common configuration problems without needing to understand Pydantic internals or search through the source code.
When Adapt successfully runs, the CLI should provide more useful information about what just happened.
For example, after a successful run, Adapt could tell the user:
what Adapt did,
which configuration was used,
where outputs were created,
what the user can try next, and
which commands/options are available for exploring other workflows.
This would help users discover Adapt's capabilities.
The current documentation does not ask to create the directory dor data.
The terminology is also important. We should consistently call this a
working directoryrather than a "repository." Calling it a repository can confuse users thinking a GitHub repository.The current workflow has too many steps for a new user:
Install → create directory → configure → create config → run
We should aim for a simpler first-run experience, ideally closer to:
Install → create working directory → run-nexrad
with Adapt creating a sensible default configuration automatically when needed.
Suggested correction or addition
For the current release, we should improve the documentation to make the existing workflow as clear as possible.
For a future release, we should revisit the overall CLI and installation design to determine how the workflow can be presented more simply and intuitively.
Acceptance Criteria
to stop press CTRL+C only once. If possible try to catch other CTRL+C to avoid early termination. Also printshutting down gracefully...So the user will know not to press CTRL+C again. or we will create new shortcut.Future Work
For a future release, we should consider a broader redesign of the installation and first-run experience rather than continuing to add instructions around a complex workflow. The goal should be to make the path from a fresh installation to a useful Adapt run as short, discoverable, and self-explanatory as possible.