Improve Bootstrap 'Quick Start' help output and/or documentation

Open
#3 0 comments 0 reactions 0 assignees View on GitHub

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

documentation

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 --help option.
  • 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 --help option, it will install the f0cal tools within a new directory f0cal within 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from f0cal/bootstrap

All issues in f0cal/bootstrap

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.