Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update instructions to run the validator #1115

Merged
merged 7 commits into from
Apr 20, 2022

Conversation

isabelle-dr
Copy link
Contributor

@isabelle-dr isabelle-dr commented Mar 16, 2022

Summary:
After receiving feedback from users on our instructions to run the validator via the command line, we identified the following pain points:

  • the user didn't know that the file downloaded from test-pack-doc needed to be unzipped to access the jar file
  • no mention that the user needs to navigate to the folder where the jar file is before running the command line (we can't use a path for the -jar argument)
  • it's not clear what the country code argument is used for
  • the fact that the command-line examples in USAGE.md aren't using the same parameter names as in README.md is confusing (the example in USAGE.md is using long names for parameters, and the example in README.md is using short names)

This PR solves these problems by:

  • Updating the instructions in the README.md
  • Adding information on what the country code is for
  • Updating USAGE.md to have more homogeneity between the two

This PR also includes:

  • an update to the description of InvalidPhoneNumberNotice in RULES.md to specify that this notice depends on the country code
  • a fix in USAGE.md to switch Java 8 to Java 11
  • added examples and fixed the requirements for the command line parameters in USAGE.md

Please make sure these boxes are checked before submitting your pull request - thanks!

  • Run the unit tests with gradle test to make sure you didn't break anything
  • Format the title like "feat: [new feature short description]". Title must follow the Conventional Commit Specification(https://www.conventionalcommits.org/en/v1.0.0/).
  • Linked all relevant issues
  • Include screenshot(s) showing how this pull request works and fixes the issue(s)

Instructions Before:

Screen Shot 2022-03-16 at 12 51 32 PM

Instructions After:

Screen Shot 2022-03-16 at 12 51 12 PM

Parameters Before:

Screen Shot 2022-03-16 at 12 53 47 PM

Parameters After:

Screen Shot 2022-03-16 at 12 54 16 PM

Copy link
Contributor

@maximearmstrong maximearmstrong left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great update! A few comments in-line before approval :)

README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated
To validate a GTFS dataset on your computer:
You can run this validator using a GTFS dataset on your computer, or from a URL.
- To validate a GTFS dataset on your computer, run the following command in the terminal, replacing the text in brackets:
- `java -jar [name of the jar file] -i [path to the GTFS file] -o [name of the output directory that will be created]`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would change this so that it is similar to my comment at line 22.

docs/USAGE.md Outdated Show resolved Hide resolved
docs/USAGE.md Outdated Show resolved Hide resolved
isabelle-dr and others added 5 commits March 27, 2022 19:34
Co-authored-by: Maxime Armstrong <46797220+maximearmstrong@users.noreply.github.com>
Co-authored-by: Maxime Armstrong <46797220+maximearmstrong@users.noreply.github.com>
Co-authored-by: Maxime Armstrong <46797220+maximearmstrong@users.noreply.github.com>
Co-authored-by: Maxime Armstrong <46797220+maximearmstrong@users.noreply.github.com>
@isabelle-dr
Copy link
Contributor Author

Thanks for the feedback, I updated the instructions to replace [ with {.
PTAL @maximearmstrong

Copy link
Contributor

@maximearmstrong maximearmstrong left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Thanks @isabelle-dr :)

@maximearmstrong maximearmstrong merged commit 29bc0ff into master Apr 20, 2022
@maximearmstrong maximearmstrong deleted the isabelle-doc-updates branch April 20, 2022 20:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants