Use a different file format for specifications to allow for diffs in git
adrianhopebailie opened this issue · comments
The current format (PDF) makes it very difficult to contribute incremental changes to the documents through pull requests.
Suggest using a text based format such as Markdown or HTML and implement a publishing workflow in a CI to output these well-formatted artefacts.
Examples:
- Markdown (published as HTML) on https://github.com/interledger/rfcs
- HTML (using the ReSpec library) on https://github.com/w3c/payment-request
- XML (published as HTML/RFC text) on https://github.com/httpwg/http-core
Thanks for the suggestion Adrian and the examples.
I agree that checking diffs wouldn't be possible with the current (PDF) format, let me discuss this and get back to you.
However, the current process is that a change (or feature request, etc.) would be drafted and submitted as a "Change Request" document (word) which will be reviewed by the relevant team (Change Control Board), discussed and then a decision is made. Also, the current understanding is to consider this repo as a "release" repo (and that the changes would only be made by owners).
However I'm open to discussing this further with you over a call based on your availability.
This should be seen as enhancing that existing process not replacing it.
By having the changes staged as pull requests the CCB can solicit input from the community on any proposed changes.
Ultimately they will be the ones with the power to merge the change in or not.
Automating the publishing is a nice-to-have
+1
When working with other parties I often advocated use of Blueprint ( https://apiblueprint.org ). This is great for diffs. You can then use tools to generate beautiful docs which can also be checked in.
@adrianhopebailie would you be up to draft a version of the API in Blueprint and submit a PR?
Thanks for the suggestion Skylar.
I'll look into Blueprint