About descriptive and normative documents

[woutermont]

There has been some confusion in recent discussions (#64, #65, and the gitter channel) about the nature of the document being drafted here. I have already tried to address this in #66, but it might be a good idea to treat it separately here. I repeat the most important part:

While it describes itself as a specification, the most voiced foundation seems to be to describe and preserve the way a limited subset of people currently use a number of other drafts within the Solid ecosystem. I do not have anything against current practices informing certain drafts, but I do think that specifications should start in a more specific need, and should be drafted based on arguments (e.g. use cases and technical considerations) rather than conservatism.

To give some examples of what I mean, statements and arguments around this document go like this:

The general purpose of this document is to describe what an app can discover based on the WebID.

The fact, however is that [social media style profiles] do exist.

Our task is to document existing practices and make recommendations related to those existing practices. [Describes current situation] That is the situation we will document.

We are documenting what exists today, [an indexing system] doesn't.

[I]t might be nice to live in a world where [preference files and extended profiles] didn't exist, but the current world isn't that one.

Our document is about things that exist.

This specification aims to describe the discovery process as it is currently in use.

[O]ur discussions [are] about what exists now with [sic] pointing out how things can be better. Our job is documenting what exists now.

Because the links we were discussing exist now whether SAI thinks they should exist or not.

That should suffice in giving an idea.

---

Now there are two things I want to point out with this approach. Firstly, there is nothing wrong with compiling an descriptive overview of current practices. To the contrary, such document would be very informative. Secondly, however, it IS wrong to conflate this with a normative specification.

Descriptive documents ... describe the current state of affairs. They don't bother thinking about the future, because they don't have to. Having normative statements in such a document would hardly make sense, unless maybe as some kind of notes to inform another separate normative document. Specifications on the other hand start from aims, compile use cases, construct a model, and mandate specific requirements based on rational arguments, in order to reach those aims. While current practices can be of concern for compatibility issues, they typically are not the primary factor of influence, definitely not in draft stages. Relying too much on the current state of things would ultimately never allow improvements to be made.

Since the above makes clear that both goals are at least partially contradictive, and should therefore ideally not live in a single document, it is rather worrying to read phrases like "[to] make recommendations," "[and] pointing out how things can be better," and "this specification aims to describe [...] as it is currently in use," in a so-called descriptive document, which also contains normative sections and conformance terms. This reads almost as if a set of practices employed by a limited set of users is being pushed on all the other users.

I would therefore ask of the contributors of this document to clarify whether it is

• a normative document, in which case arguments simply referring to the current state of things are no longer valid;
• a descriptive document, in which case the label "specification" and the conformance terms should be removed from the document;
• a conflation of both, in which case the document should be split up in two.

[jeff-zucker]

I would therefore ask of the contributors of this document to clarify whether it is [informative, descriptive, both]

It's likely that we will have both normative statements and best practices statements. We are revising the current document based on feedback about conformance rules. Please watch upcoming PRs and flag any you object to.

Specifications on the other hand start from aims, compile use cases, construct a model, and mandate specific requirements based on rational arguments, in order to reach those aims.

The fact that we base ourselves on current practices is not mutually exclusive with any of those things and if you look over our meeting notes, you will see we've done a lot of that.

a conflation of both, in which case the document should be split up in two.

That's one opinion. Most specifications I can think of include both normative and non-normative text.

Relying to much on the current state of things would ultimately never allow improvements to be made.

And ignoring them would promote chaos and not provide a path forward since things always start where they are.

[woutermont]

Specifications on the other hand start from aims, compile use cases, construct a model, and mandate specific requirements based on rational arguments, in order to reach those aims.

The fact that we base ourselves on current practices is not mutually exclusive with any of those things and if you look over our meeting notes, you will see we've done a lot of that.

That is true, but the fact that you base yourselves on current practices only is what bothers me. That is exactly what the minutes show: you start in current practices, select the one you think is best (granted, through rational argumentation), and possible fine-tune a bit here and there. What a spec should do, is to formulate a goal (other than "describe what's there"), start in that goal, and compare current practices with theoretically interesting models.

It's likely that we will have both normative statements and best practices statements. [...] Most specifications I can think of include both normative and non-normative text.

Of course, best practices and non-normative text is valuable, I never denied that. What I am complaining about is the use of descriptive text AS normative text. A sentence describing how things are CANNOT also specify how things should be, simply because these things are (often) not the same. It is this incompatibility of norms and descriptions in the WebID-Profile "spec" which endangers the progression of Solid. Making the descriptive normative, i.e. recommending to do exactly as things are, not only creates a standstill for implementations following this "spec", but also renders them uninteropperable with implementations that do not follow it (as pointed out by a.o. @RubenVerborgh, @elf-pavlik and myself in relation to WebID-Profile, SAI and TypeIndexes).

Relying to [sic] much on the current state of things would ultimately never allow improvements to be made.

And ignoring them would promote chaos and not provide a path forward since things always start where they are.

Where did I say we have to ignore current practices? As I've stated in multiple comments in this repo, compatibility with existing implementations can definitely be a concern. But "compatibility" does not mean "make current practice the norm"; it means "make sure that current practice still works acceptably with practices fully implementing the norm." As I've pointed out in #65 (comment), I have up till now not seen a clear argument why compatibility with current practice cannot be achieved by a radically different norm. In the extreme, we could do all discovery out of band, pay people to manually check each "old school" WebID, and still be compatible with current practices (though this would of course fail any sane test of efficiency).

[woutermont]

In summary, what I mean is: let's stop worshipping current practice as the norm (WebID-Profile) or building theoretically elegant models without concern for current practice (SAI), and bundle our efforts to find a way to combine the two. This is i.m.o. best done by splitting up into focussed mixes, as argued for in #66.