search

solid / webid-profile

Discovery based on Solid Social Agent WebID
https://solid.github.io/webid-profile/
MIT License
12 stars 9 forks source link

Replace term "pod" with "storage" or "server" as appopriate in Solid WebID Profile #71

Closed csarven closed 2 years ago

csarven commented 2 years ago

The term "pod" is not defined or used towards conformance in the Solid Protocol or in other Work Items.

The references to "pod" in the Solid WebID Profile is dangling in that it is not associated with a particular conformance requirement.

The suggestion here is to consider replacing "pod" with "storage" or "server" as appropriate in Solid WebID Profile.

VirginiaBalseiro commented 2 years ago

Related: #70

jeff-zucker commented 2 years ago

May I ask why this is the case? I can not see "pod" being replaced by "storage" in texts aimed at the general public so not using the term in the spec seems confusing.

jeff-zucker commented 2 years ago

Can we do something in the terminology section that says that the term "pod" is loosely defined in common parlance but that in this document it will exactly mean a pim:Storage?

csarven commented 2 years ago

"pod" is informal. "storage" is in Solid Protocol and used in conformance requirements, in the same way "server" or "MUST" or "Link" or "acl" or whatever are well-defined and used.

For all intents and purposes, this technical report is not aimed at the general public. We should certainly aim to make the content more usable, and there are guidances on that we can orient ourselves with, e.g., https://www.w3.org/TR/coga-usable/ as mentioned in https://solidproject.org/ED/protocol#web-content-accessibility ) . Even without the technicalities of Solid, "storage" is demonstrably a more widely used term than "pod" by the general public.

The document should use "storage" for anything pertaining to conformance. "storage" should be part of the terminology (if needed), and can cite TR/protocol#storage - aside: I will soon introduce that term besides the current section in the spec.

Using "pod" and "storage" interchangeably will only complicate rather than simplify as I see it. "Pod" can be used as a reminder for some readers that may be familiar with the term from elsewhere - definitely not from other Solid work items - so I'd suggest to limit its use to be one time and along the lines of "... (also known as pod)".

Edit: I strongly suggest to not use "pod".

jeff-zucker commented 2 years ago

Okay, the word "p-d" shall never cross my lips again. The Solid-OIDC spec and interoperability spec use "Resource Server" which is not intuitively clear to me, would "Solid storage provider" work? [EDIT, added this:] Is "Solid server" the same thing as a "Solid Resource Server" or is can a "Solid server" also be just an identity provider. Or is "Solid server" another junk term with no precise meaning?

acoburn commented 2 years ago

FWIW, in the context of OAuth2/OpenID Connect, "Resource Server" is a well-defined concept. Furthermore, there are many servers in the Solid ecosystem that could be called a Resource Server (Solid Storage is one of those), and for Solid-OIDC, the spec is really referring to that larger concept of resource server. This is another reason why it is important to be precise with the terminology.

jeff-zucker commented 2 years ago

@csarven - is this then something that will be replaced :

data pod A data pod is a place for storing documents, with mechanisms for controlling who can access what.

@acoburn wrote

there are many servers in the Solid ecosystem that could be called a Resource Server (Solid Storage is one of those)

What term do you suggest I use for a server which hosts Solid storages?

csarven commented 2 years ago

Right. There is no #data-pod in ED/protocol and so there won't be one at TR/protocol in the next release.

Bear with me as I'll add storage, server, client, among other terms, and conformances classes to ED/protocol soon. WebID Profile can link to them directly when it is referring to them, e.g.:

In https://solidproject.org/TR/wac#terminology :

In addition to the terminology above, this specification also uses terminology from the [INFRA] specification. When INFRA terminology is used, such as string and boolean, it is linked directly to that specification.

In https://solid.github.io/notifications/protocol#terminology :

In addition to the terminology above, this specification also uses terminology from the [SOLID-PROTOCOL] specification. When SOLID-PROTOCOL terminology is used it is linked directly to that specification.

We may need to get into the habit of linking to concepts in versioned technical reports (/TR/{YYYY}/{shortname}#{concept}) if there is one available because /TR/{shortname}#{concept} is not intended to be persistent - latest published version - so fragments may change or disappear. Not super cool, I know. I'll add some of these guidelines to CONTRIBUTING.md...