Re: Writing specifications for the current protocol

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>
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
> >>
> >>
> >>
> >>
> >
>
>