Re: Writing specifications for the current protocol

I’d be up for a call.

— David

David Newbury
Enterprise Software Architect, Getty Digital

Email: dnewbury@getty.edu<mailto:dnewbury@getty.edu>
Phone: (310) 440-6116

From: Thad Guidry <thadguidry@gmail.com>
Date: Sunday, December 15, 2019 at 7:10 AM
To: Antonin Delpeuch <antonin@delpeuch.eu>
Cc: "public-reconciliation@w3.org" <public-reconciliation@w3.org>
Subject: Re: Writing specifications for the current protocol
Resent-From: <public-reconciliation@w3.org>
Resent-Date: Sunday, December 15, 2019 at 7:09 AM

I think a call would be good !

I also have various suggestions on grammar improvements and clarifications.

I'll begin issuing various PR's for these for review.

Thad
https://www.linkedin.com/in/thadguidry/



On Sun, Dec 15, 2019 at 8:32 AM Antonin Delpeuch <antonin@delpeuch.eu<mailto:antonin@delpeuch.eu>> wrote:
Hi all,

I think the specs now cover all the features of the API I am aware of.
We have a much better documentation of the current API, which should be
useful for anyone who wants to implement clients or services which are
compatible with the existing ones.

I have turned it into a draft here:

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


The 0.1 version number is here to indicate that it's far from final -
many improvements have been discussed here, and we should implement them
in new versions of the protocol. We can now do so there:

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


We can still make editorial changes to v0.1 (or add features that are
already implemented but not documented). I will also try to set up some
workflow to replicate editorial changes to the latest version on the
previous ones when applicable.

Perhaps it would be worth setting up a regular call so we can discuss
changes more thoroughly, now that we actually need to take some
decisions about the changes we make (rather than documenting existing
stuff)?

Cheers,

Antonin

On 26/11/2019 21:34, Antonin Delpeuch wrote:
> 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
>>
>>
>>
>>
>

CAUTION: This email originated from outside of the Getty. Do not click links or open attachments unless you verify the sender and know the content is safe.