Doc cleanup (#75)

* Clean up documentation and readmes

* Add tenet of JMESPath, guiding the distinction between syntax and functions

Author: innovate-invent

.github/pull_request_template.md

@@ -21,7 +21,7 @@ Please keep PR discussion strictly about the content of the PR and any comments
 | **[SemVer](https://semver.org/spec/v2.0.0.html#summary)** | MAJOR\|MINOR\|PATCH
 | **[Discussion #](https://github.com/jmespath-community/jmespath.jep/discussions)** | [##](https://github.com/jmespath-community/jmespath.jep/discussions/##)
 
-*Please discuss the merit of the JEP in the linked discussion. PR discussion should be limited to proofing the content of the PR and the PR proposal inital comment*
+*Please discuss the merit of the JEP in the linked discussion. PR discussion should be limited to proofing the content of the PR and the PR proposal initial comment*
 
 ## Abstract
 

README.md

@@ -1,16 +1,14 @@
 # JMESPath Specification
 
 Any changes to the JMESPath specification
-(https://jmespath.site/specification.html) must have a JEP (JMESPath Enhancement
-Proposal) which is tracked in this repo.  There are implementations of JMESPath
-in over 9 different languages, and we want to make sure that any modifications
-to the spec make sense for all JMESPath libraries.  A JEP helps to work through
-the design process for new additions and ensures that the JMESPath community
-has a chance to give feedback before it's officially part of the specification.
+(https://jmespath.site/specification.html) must have a JEP (JMESPath Enhancement Proposal) which is tracked in this repo. There are implementations of
+JMESPath in over 9 different languages, and we want to make sure that any modifications to the spec make sense for all JMESPath libraries. A JEP helps
+to work through the design process for new additions and ensures that the JMESPath community has a chance to give feedback before it's officially part
+of the specification.
 
 ## Things that need a JEP
 
-Any functionaly change that would require an update to the specification
+Any functionality change that would require an update to the specification
 (http://jmespath.site/specification.html) requires a JEP.
 
 This includes, but is not limited to:
@@ -21,44 +19,34 @@ This includes, but is not limited to:
 
 ## Things that do not need a JEP
 
-Anything that is specific to a JMESPath library does not need a JEP.  You
-should defer to the specific library's contributing guide.  This can include
-additional language specific APIs, extension points (e.g. adding custom
-functions), configuration options, etc.
+Anything that is specific to a JMESPath library does not need a JEP. You should defer to the specific library's contributing guide. This can include
+additional language specific APIs, extension points (e.g. adding custom functions), configuration options, etc.
 
 ## Guidelines for proposing new features
 
-First, make sure that the feature has not been previously proposed.  If it has,
-make sure to reference prior proposals and explain why this new proposal should
-be considered despite similar proposals not being accepted.
+First, make sure that the feature has not been previously proposed. If it has, make sure to reference prior proposals and explain why this new
+proposal should be considered despite similar proposals not being accepted.
 
-Writing a JEP can be a lot of work, so it can help to get initial guidance
-before getting too far.  You can chat on the JMESPath gitter channel
+Writing a JEP can be a lot of work, so it can help to get initial guidance before getting too far. You can chat on the JMESPath gitter channel
 (https://gitter.im/jmespath/chat) to get an initial pulse of a new feature.
 
-You can also create a discussion in this repo with a rough proposal
-to get initial high level feedback. If you'd like to move
-forward with the proposal you will still need to write a JEP
-and send a pull request (PR).
+Then open a [discussion](https://github.com/jmespath-community/jmespath.spec/discussions) to discuss the feature, its merit, and any possible
+alternatives. Once the discussion has reached a mature level of feedback it will be assigned a JEP#. At this point it is safe to begin composing a
+JEP, along with all the required changes and documentation.
 
 ### Tenets of JMESPath
 
-When proposing new features, keep these tenets in mind.  Adhering to
-these tenets gives your proposal a higher likelihood of being accepted:
+When proposing new features, keep these tenets in mind. Adhering to these tenets gives your proposal a higher likelihood of being accepted:
 
-* JMESPath is not specific to a particular programming language.  Avoid
-  constructs that are difficult to implement in another language.
+* JMESPath is not specific to a particular programming language. Avoid constructs that are difficult to implement in another language.
 * JMESPath strives to have one way to do something.
 * Features are driven from real world use cases.
+* Syntax is generally used to express data structure manipulation while functions are used to express datum manipulation
 
 # JMESPath Compliance Tests
 
-This repo contains a suite of JMESPath compliance tests. JMESPath's implementations can use these tests in order to verify their
-implementation adheres to the JMESPath spec.
-
-## Test Organization
-
-`grammar/*.yml` contains tests for general grammar functionality. These documents must validate against the `grammar_schema.yml`.
-
-`functions/*.yml` contains a description of each function accompanied by a suite of tests/examples. These documents must validate against the `function_schema.yml`.
+This repo contains a suite of JMESPath compliance tests. JMESPath's implementations can use these tests in order to verify their implementation
+adheres to the JMESPath spec. Every implementation of JMESPath should provide a basic command line executable that allows execution of compliance
+tests. This eases third-party validation of the implementation, without needing any specific testing suite.
 
+See [bin/README.md](bin/README.md) for more information on running compliance tests.

bin/README.md

@@ -1,26 +1,25 @@
 # JMESPath Compliance Tests
 
-This repo contains a suite of JMESPath compliance tests. JMESPath's implementations can use these tests in order to verify their
-implementation adheres to the JMESPath spec.
+This repo contains a suite of JMESPath compliance tests. JMESPath's implementations can use these tests in order to verify their implementation
+adheres to the JMESPath spec.
 
 ## Test Organization
 
 `grammar/*.yml` contains tests for general grammar functionality. These documents must validate against the `grammar_schema.yml`.
 
-`functions/*.yml` contains a description of each function accompanied by a suite of tests/examples. These documents must validate against the `function_schema.yml`.
+`functions/*.yml` contains a description of each function accompanied by a suite of tests/examples. These documents must validate against
+the `function_schema.yml`.
 
 ## Running Tests
 
-This repository include a Python `jp-compliance` executable test runner.
+This repository includes a Python `jp-compliance` executable test runner.
 
 ```
 jp-compliance <executable> <test yaml> [<test name>..]
 ```
 
-This will run the JMESPath compliance tests against a JMESPath executable.
-The executable must accept the query as the only argument, and the input data on stdin.
-The result must be printed to stdout as JSON.
-Errors must be printed to stderr and match expected values.
+This will run the JMESPath compliance tests against a JMESPath executable. The executable must accept the query as the only argument, and the input
+data on stdin. The result must be printed to stdout as JSON. Errors must be printed to stderr and match expected values.
 
 If your executable requires additional arguments, wrap it in an executable script.