Writing specifications for the current protocol

Hi all,

How about we start writing proper specifications for the reconciliation
API? I think it would be very useful to have clean and precise
specifications of the protocol for anyone who wants to use or develop a
service.

I have set up a repository for that:

https://github.com/reconciliation-api/specs

The current draft can be viewed at:

https://reconciliation-api.github.io/specs/

I propose that we start by documenting the current state of the API,
without adding the improvements that we intend to make so far. We can
build on the existing documentation:

https://github.com/OpenRefine/OpenRefine/wiki/Reconciliation-Service-API

We can open issues on the specs repository to document any problems we
want to address in an improved version of the specification, or any
unclear areas where we are looking for clarification from others.

To edit the specs, only rudimentary knowledge of HTML should be
required. Feel free to commit directly to master for uncontroversial
changes or use pull requests if you want to get your edits to be
reviewed by others.

After cloning the repositiory you will be able view the document locally
with your browser (no compilation required).

I have added some initial structure which we can improve, with comments
about what sort of content I am thinking of for the first few sections -
all this can be improved, these are just suggestions.

Let me know if anything is holding you back from editing - hopefully the
workflow should be simple for everyone.

Best,

Antonin

Received on Monday, 16 September 2019 14:16:38 UTC