Provide documents in a format that allows for feedback and discussion

ROBERT-proximity-tracing / documents

Protocol specification, white paper, high level documents, etc.

Other

247 stars 21 forks source link

Provide documents in a format that allows for feedback and discussion #4

Open MattiSG opened 4 years ago

MattiSG commented 4 years ago

The documents are currently provided only as binary files in the PDF format. This choice makes it hard to collaborate and prevents suggestions of improvements through the standard open-source practices of pull (or “merge”) requests, forking for creating derived protocols, and discussion at line-level.

These documents look like they were created with LaTeX. The LaTeX sources should be provided in this repository instead of PDF files. The generated PDF files could be provided for consumption through another mean such as a public website, or at least in a dedicated folder such as dist.

jjerphan commented 4 years ago

The generated PDF files could be provided for consumption through another mean such as a public website, or at least in a dedicated folder such as dist.

Alternatively, a CI pipeline could be set to compile the latest version of the document and make it available.

Maybe using Markdown could be sufficient at this level?

Keirua commented 4 years ago

Given the phrasing in the readme:

We will be happy to receive your constructive comments and questions using
the standard "issues" tab above.
The "pull requests" tab is not expected to be usefull in this context.

I'd had that the open-source way of working is not clear to me:

is this repository meant for open-source collaboration in the way it's usually done in the open-source community, where many people contribute through pull requests and contributions are included?
is this repository a communication tool, where only questions/issues can be raised, then the owner of the repository will find answers, and possibly include a clarification/improvement in an updated version of the documents?

Keirua commented 4 years ago

Also, providing binary files make it particularly hard to review changes and follow the evolution of the document. In the following examples (that's a minor edit, but it would be worse for large modifications):

we have to trust you that no other changes were made (or to use a pdf-diffing tool, which is way less convenient)
with a text file, it could be very easy to note that there were no other charges, it would actually be useless to state it

PRIVATICS-Inria commented 4 years ago

Thanks @MattiSG and @Keirua for your suggestions.

To clarify, we plan to use github as a communication tool where anybody can comment and discuss our proposal (option 2 of @Keirua ). The documents of this repository will be regularly updated based on our internal work and the comments received through github.

Currently, we cannot open the latex source file, this latter is not stable enough (e.g., next version may significantly change the doc). Honestly speaking, we also need to sanitize the latex source file which we did not find time to do so far ;-). Once these two aspects will be solved, we’ll open them. Sorry for the inconvenience in the meantime.

MattiSG commented 4 years ago

Thanks @PRIVATICS-Inria for replying and clarifying your intentions.

However, I must say I am quite confused and disappointed by this answer.

Version control is precisely useful for following changes, including significant ones, and the argument of waiting for stability before opening the source is rather hard to understand considering the resulting content is already public. As for sanitisation, this is exactly an example where collaboration with the wider public could be beneficial: I am quite confident that you would get contributions to refactor the source, leaving you more time to improve the protocol.