update README and contributing doc

CONTRIBUTING.md

@@ -13,14 +13,14 @@ Suggested changes to this schema can be initiated as [**Issues**](https://github
 
 Even those with write access to the main repository should in general create pull request branches within their own forks. This way when the main repository is forked again, the new fork is created with a minimum of extraneous volatile branches.
 
-> To facilitate review of external pull requests, users are encouraged to activate [**Travis CI**](https://travis-ci.org/) to monitor the build status (documentation, Swagger UI) of their fork. By following the documentation for [deployment to GitHub Pages](https://docs.travis-ci.com/user/deployment/pages/) and adding a `$GITHUB_TOKEN` environment variable to their repo configuration, pushes to the forked repo should be viewable relative to `https://[user-or-org].github.io/workflow-execution-service-schemas/preview/<branch>`:
+> To facilitate review of external pull requests, users are encouraged to activate [**Travis CI**](https://travis-ci.org/) to monitor the build status (documentation, Swagger UI) of their fork. By following the documentation for [deployment to GitHub Pages](https://docs.travis-ci.com/user/deployment/pages/) and adding a `$GITHUB_TOKEN` environment variable to their repo configuration, pushes to the forked repo should be viewable relative to `https://[user-or-org].github.io/workflow-execution-service-schemas/preview/<branch>/`:
 
 + https://[user-or-org].github.io/workflow-execution-service-schemas/preview/[branch]/docs/
 + https://[user-or-org].github.io/workflow-execution-service-schemas/preview/[branch]/swagger-ui/
 + https://[user-or-org].github.io/workflow-execution-service-schemas/preview/[branch]/swagger.json
 + https://[user-or-org].github.io/workflow-execution-service-schemas/preview/[branch]/swagger.yaml
 
-> Providing this base URL in the pull request comment is appreciated, but not required.
+> Providing this base URL in the pull request comment is appreciated, but not required. When creating a pull request from the forked repository's `develop` branch, the base URL will just be `https://[user-or-org].github.io/workflow-execution-service-schemas/`.
 
 If a security vulnerability is identified with the specification please send an email to [email protected] detailing your concerns.
 

README.md

@@ -31,7 +31,7 @@ API Definition
 --------------
 
 See the human-readable [Reference Documentation](https://ga4gh.github.io/workflow-execution-service-schemas/docs/) 
-and the [OpenAPI description](openapi/workflow_execution_service.swagger.yaml). You can also explore the specification in [Swagger Editor](https://editor.swagger.io/#/?import=https://ga4gh.github.io/workflow-execution-service-schemas/swagger.yaml).
+and the [OpenAPI description](openapi/workflow_execution_service.swagger.yaml). You can also explore the specification in [Swagger UI](https://ga4gh.github.io/workflow-execution-service-schemas/swagger-ui/) or [Swagger Editor](https://editor.swagger.io/#/?import=https://ga4gh.github.io/workflow-execution-service-schemas/swagger.yaml).
 
 Use Cases
 ---------
@@ -43,21 +43,27 @@ Use cases include:
 
 Possible Future Enhancements
 ----------------------------
+
 * common JSON parameterization format that works with CWL and WDL
 * validation service for testing WES implementations' conformance to the spec
 * improved tools for troubleshooting execution failures, especially when there are 100s-1000s of tasks
-* a callback mechanism for monitoring status changes in running workflows (e.g. a webhook)
-* integration with GA4GH data access APIs (e.g. htsget, DOS)
+* a callback mechanism for monitoring status changes in running workflows (e.g., a webhook)
+* integration with GA4GH data access APIs (e.g., htsget, DOS)
 
 How to View
 ------------
-- Documentation: https://ga4gh.github.io/workflow-execution-service-schemas/docs/
-- Full API specification (OpenAPI YAML): https://ga4gh.github.io/workflow-execution-service-schemas/swagger.yaml (or view in [Swagger Editor](https://editor.swagger.io/#/?import=https://ga4gh.github.io/workflow-execution-service-schemas/swagger.yaml))
+
+* Documentation: https://ga4gh.github.io/workflow-execution-service-schemas/docs/
+* Full API specification:
+    * OpenAPI YAML: https://ga4gh.github.io/workflow-execution-service-schemas/swagger.yaml 
+    * OpenAPI JSON: https://ga4gh.github.io/workflow-execution-service-schemas/swagger.yaml
+    * Swagger [UI](https://ga4gh.github.io/workflow-execution-service-schemas/swagger-ui/) or [Editor](https://editor.swagger.io/#/?import=https://ga4gh.github.io/workflow-execution-service-schemas/swagger.yaml))
 
 How to Contribute Changes
 -------------------------
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
+
 If a security issue is identified with the specification, please send an email to [email protected] detailing your concerns.
 
 License