Getting Started Documentation Feels Inadequate

[droidchef]

Describe the task The documentation provided in the form of README.md seems inadequate in terms of getting started with the Annotator on a new project.

Expected behavior Follow the steps listed on the readme and successfully get the annotations applied on your module.

Actual behavior Need to do a lot of hit and trials, jump from one page to another, just to get hit by error after error and try to resolve them manually.

I am posting a list of questions which when answered could help spruce up the Readme or can be added to a GettingStarted.md or Installation.md file so that people don't have to spend so much time going through the process of just getting this project to work.

• [ ] Installation It would be nice to provide a cURL or wget command to just pull the jar from maven. Like so

  curl -O https://repo.maven.apache.org/maven2/edu/ucr/cs/riple/annotator/annotator-core/1.3.15/annotator-core-1.3.15.jar

  OR

  wget https://repo.maven.apache.org/maven2/edu/ucr/cs/riple/annotator/annotator-core/1.3.15/annotator-core-1.3.15.jar

I'll leave the format of the command to the authors to decide. You could either have the latest version hardcoded so that it is easily copy/pasteable OR to have a placeholder that says {version-code-here} which the user then needs to manually substitute.

• [ ] Fix Broken link to AnnotatorScanner

  AnnotatorScanner checker must be activated with version >= 1.3.6, see more about AnnotatorScanner [here](https://github.com/ucr-riple/NullAwayAnnotator/blob/type-annotator-scanner/README.md).

• [ ] nullaway and scanner configuration file templates or schemas missing

The guide mentions that these files do not need to be created during the initial project setup. But in the very next paragraph the user is asked to provide the path to these files.

This feels confusing. One can touch these files on the command line but what should they contain? I couldn't get the script to create these files for me so I have been guessing the schema for these XML files based on the source code in the project but that didn't help much.

So can we provide some templates for these files that one can just copy/paste and get started?

• [ ] Annotator jar hides all the build output which makes debugging hard

So the -bc command hides all the output that would be otherwise logged by gradle. One tip we could add here is to forward the standard output of gradle build to stderr by adding 1>&2 at the end of the build command. This makes debugging a lot easier, especially when you are getting started with this project.

• [ ] config.json removed from the readme file In the earlier versions I saw a config file being provided and passed into the jar to manage the configurations easily, is there a reason why it was removed?

• [ ] template command missing required arguments so the purpose of the command fails because again it cannot be simply copy/pasted

The template command is missing -cn argument which is mentioned as must provide arg. We should update in the template command.

Happy to submit a PR if the issues and their corresponding suggestions seem useful for maintainers and adopters.

P.S. - I am trying to integrate this in a project myself with not much luck so far. So answers to some of the questions above could also help me unblock myself.

[nimakarimipour]

@droidchef Thank you very much for reporting this! All your questions are very helpful, and I’ll work on updating the documentation accordingly. I really appreciate your suggestions. Once we finalize some decisions, like deprecating or keeping config.json and resolving other small issues, I’ll inform you. If possible, I’d love for you to make a PR, or I’ll update it myself with your suggestions. Thanks.