Task: rewrite Solid spec in W3C template

solid / solid-spec

Solid specification draft 0.7.0

Creative Commons Zero v1.0 Universal

1.13k stars 103 forks source link

Task: rewrite Solid spec in W3C template #170

Open RubenVerborgh opened 5 years ago

RubenVerborgh commented 5 years ago

The current Solid specification has a couple of issues;

It is a collection of Markdown documents, as opposed to a single authoritative document
The specification contains parts that are (purposely) not implemented
Some parts that are implemented (and necessary) are not in the spec
The spec is insufficiently precise to be implemented in an unambiguous way

As such, I propose to start from scratch with a Solid spec in a W3C template, where we pull in curated parts of the current Solid v0.7 spec, with the aim of reaching a v1.0.

Mitzi-Laszlo commented 5 years ago

https://www.w3.org/StyleSheets/TR/2016/readme.html

elf-pavlik commented 5 years ago

I suggest https://tabatkins.github.io/bikeshed/ many specs on REC track use it and it still allows using convenient markdown.

justinwb commented 5 years ago

As such, I propose to start from scratch with a Solid spec in a W3C template, where we pull in curated parts of the current Solid v0.7 spec, with the aim of reaching a v1.0.

I'm in 100% agreement with this proposal.

Mitzi-Laszlo commented 5 years ago

Perhaps in a new repo GitHub.com/solid/specification?

michielbdejong commented 5 years ago

+1 to converting the format +1 to fixing points where the text diverts from current practice +1 to fixing ambiguities -1 to "pull in curated parts" if by that you mean making changes to the meaning of the spec -1 to " the aim of reaching a v1.0" if by that you mean changing its technical details into different ones

In this phase (I would say from now to roughly the end of 2019), we should only change the spec to make it better describe the current practice, or to fix (security) bugs.

RubenVerborgh commented 5 years ago

-1 to "pull in curated parts" if by that you mean making changes to the meaning of the spec -1 to " the aim of reaching a v1.0" if by that you mean changing its technical details into different ones

conflict with

+1 to fixing points where the text diverts from current practice

but I agree with the overall sentiment.

RubenVerborgh commented 5 years ago

But really, we should move away from the idea that v0.7 is untouchable, or even a spec. It's mainly a set of documentation written together, without any consensus process or anyone wondering whether something is a good idea. Let's have a minimum of oversight here.

Regarding timeline specifically:

In this phase (I would say from now to roughly the end of 2019),

Why wouldn't we want a v1.0 by the end of 2019?

RubenVerborgh commented 5 years ago

Follow-up in https://lists.w3.org/Archives/Public/public-solid/2019May/0009.html and https://github.com/solid/specification