Re: Writing specifications for the current protocol

Hi all,

We are making good progress on the specs, you can see the current result
here:

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

Feel free to chime in, there are still plenty of things that can be
added or improved.

If you ever have implemented reconciliation services, and if you can
remember struggling with the documentation on OpenRefine's wiki, you can
make sure these new specs fix them.

As usual if you haven't got push access to the GitHub repository, check
https://github.com/reconciliation-api where you should see a pending
invitation - if not just let me know what is your GitHub username.

Cheers,

Antonin

On 16/09/2019 15:16, Antonin Delpeuch wrote:
> 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 Tuesday, 26 November 2019 20:34:14 UTC