Improve Bootstrap 'Quick Start' help output and/or documentation
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 45/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- python
- Domain
- cli, documentation
Research direction
Start by running curl bootstrap.f0cal.com/master | python3 - --help and inspect the bootstrap script's help output and the post-install f0cal/README.md instructions. Compare the current output with the requested introduction, usage example, option descriptions, and next steps; the work is done when a first-time user can understand what bootstrap installs, how to run it, and what to do afterward.
Written by the indexing model from the issue text.
Description
The 'Quick Start' experience is a bit cryptic. Among the documentation, the help message, and the code, none clarifies what this is doing, what to expect, or what to do next.
As-run:
curl bootstrap.f0cal.com/master | python3 - --help
Problems:
- There is not a clear division between the download and the help content.
- It is not clear what application or workflow this help is for.
- It is not obvious what the bootstrap is supposed to accomplish when run without
--help. - It is not obvious how to run bootstrap without the
--helpoption. - It is not clear what to do after the bootstrap install, such as how to start the f0cal CLI.
Suggested changes (for --help):
- Add a header, including leading whitespace to separate it from the curl download output.
- Add an introduction. Explain that this is the f0cal bootstrap script to set up f0cal tools on the local computer. Explain that when run without the
--helpoption, it will install the f0cal tools within a new directoryf0calwithin the current directory, (actions related to new or existing virtual environment, or lack thereof, TBD... see other issues), then install system packages. - Add a usage example.
For example:
(whitespace)
********************
* Welcome to f0cal *
********************
When run without the --help flag, this bootstrap script will perform the following actions:
1. Download and install f0cal tools within a new directory ./f0cal/.
2. (actions related to new or existing virtual environment, or lack thereof)
3. Install system packages such as compilers, unless run with --skip-system-packages.
Usage:
- [-h] [-d] [-v VENV_DIR] [--no-sudo] [--skip-system-packages] {git,local,pip}
positional arguments:
{git,local,pip}
git Install from GitHub
optional arguments:
-h, --help Show this help message and exit
-d, --debug Enable debug logging
-v VENV_DIR, --venv-dir VENV_DIR
Directory at which to create python virtual environment
--no-sudo Install without sudo
--skip-system-packages
Do not install system wide packages such as compilers
Usage example:
curl bootstrap.f0cal.com/master | python3 - -v f0cal/venv git
# Install from GitHub, using a new virtual environment for python packages, and include system wide packages.
After bootstrap installation, continue with instructions in f0cal/README.md.
- Dominant language
- Python
- Stars
- 1
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from f0cal/bootstrap
-
enhancement
Difficulty 3/5 1-2 days Newbie friendliness 45/100
-
Difficulty 3/5 1-2 days Newbie friendliness 35/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 45/100
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100