docs

Author: fehguy

DEVELOPMENT.md

@@ -1,14 +1,14 @@
 ## Development Guidelines
 
-Establish guidelines which build a transparent, open mechanism for deciding how to change the specification.  The TCB will initially follow these processes when merging changes from external contributors or from the TCB itself, and adjust them as it makes sense.
+This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The Open API Technical Contributor Board will initially follow these processes when merging changes from external contributors or from the TCB itself. This guideline document will be adjusted as it makes sense.
 
 ## OAI Specification Driving factors
 
-The spec should be use-case driven.  We can write support for hypothetical use cases as we see fit, but they should be backed by realistic scenarios
+The OpenAPI Specification should be use-case driven.  We can write support for hypothetical use cases as we see fit, but they should be backed by realistic scenarios
 
-## Specification change criteria
+## Specification Change Criteria
 
-The specification _will change_ from the 2.0 version.  We should typically do so when any of the following criteria are met:
+The specification _will change_ from the original 2.0 version.  We should typically do so when any of the following criteria are met:
 
  - Clarity.  The current "way" something is done doesn't make sense, is complicated, or not clear
  - Consistency.  A portion of the specification is not consistent with the rest, or the industry standard terminology
@@ -25,7 +25,7 @@ The specification _will change_ from the 2.0 version.  We should typically do so
  - Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal
  - New features should be done in feature branches which, upon approval, be merged into the OpenAPI.next branch.
  - Use labels for the workflow of specification changes.  For example, this may be labeled as `proposed`, `needs migration review`, `needs tooling review`, `needs documentation`, `rejected`, `needs approval`.  These labels must be assigned by project committers
- - An issue will be opened for each feature change.  Embedded in the issue OR ideally linked in a file via PR, a document should be supplied for use cases for the change
+ - An issue will be opened for each feature change.  Embedded in the issue OR ideally linked in a file via pull-request (PR), a document should be supplied for use cases for the change
  - A PR will be used to describe the _proposed_ solution, and linked to the original issue
  - Not all committers will contribute to ever single proposed change.  There may be many open proposals at once, and multiple efforts may happen in parallel
  - When the OpenApi.next spec is complete and approved for release, the branch will be merged to master.
@@ -46,5 +46,6 @@ No change should be approved until there is documentation for it, supplied in an
 
 We should always be as transparent as possible.  Sometimes there will be discussions that use customer names, sensitive use cases, etc.  These must be anonymized, discussed in a private repository, or offline
 
- - Offline Discussions should live in issues.
- - Realtime discussions should be in a public chat such as IRC or Slack
+ - Asynchronous discussions should live in the GitHub issues for this project
+ - Realtime discussions should be in a public chat such as IRC or Slack
+

README.md

@@ -10,12 +10,14 @@ You can see the current process for development inside the OpenAPI Specification
 
 ## Participation
 
-The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. It encourages participation from individuals and companies alike.  If you wish to participate in the evolution of the OpenAPI Specification, please consider the following:
+The OpenAPI Specification is a community driven, open project hosted by the Linux Foundation. The OAI encourages participation from individuals and companies alike. If you wish to participate in the evolution of the OpenAPI Specification, please consider the following:
 
 * Review the [current specification](). The human-readable markdown file _is the source of truth_ for the specification.
 * Review the [development](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md) process so it's clear how the spec is evolving.
 * Check the [issues](https://github.com/OAI/OpenAPI-Specification/issues) and [pull requests](https://github.com/OAI/OpenAPI-Specification/pulls) to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by adding a comment to the existing issue or PR.
-* Create an issue to describe a concern and/or a pull request to provide a solution. If providing a pull request, please ensure you are adding comments regarding the **Approving Changes** section of the [development](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md) guideline.
+* Create an issue to describe a new concern along with, if possible, a proposed solution.
+
+Be aware that all feedback cannot be accommodated and there may be solid arguments to/from a change being appropriate for the specification.
 
 ## License
 

versions/3.0.md

@@ -0,0 +1,5 @@
+# OpenAPI Specification
+
+#### Version 3.0
+
+(coming soon)