Making Abstract abstract, instead of introduction

[TallTed]

pulled from #1554

---

Preview | Diff

[iherman]

Approving after the merge of #1560 (comment)

[msporny]

I don't find this change to be an improvement on the first paragraph that someone that doesn't know about the specification would find helpful for the following reasons:

• It doesn't explain what a verifiable credential is (it introduces the concept too early)
• It starts talking about cryptography without making it clear why it matters
• It injects jargon like "cryptoperiod" into the second sentence the reader reads
• It makes no mention of the data model or what we're trying to accomplish with the specification
• It skips over most of the middle of the spec and then starts identifying things we talk about in the security and privacy considerations.

I don't think we do the readers a favor in exposing them to this paragraph as the first thing they read about the specification. I know that I would get a bad impression of the specification if this were the first thing I read about it.

I do think it would be useful to have this text in a "This is what this specification contains" with pointers to each section. That would go well in the introduction, so that's not to say that we shouldn't include this text, just not as the very first thing that someone reads.

I'll also note that the Abstract does need work; it's dated and could use a bit of "oomph" in the last sentence or two.

IOW, keep the first two sentences, I like them. The last sentence isn't great:

These credentials provide benefits to us when used in the physical world, but their use on the Web continues to be elusive.

We need to modernize that statement, and we probably have space for one or two more high-level but impactful statements regarding the vision of the technology.

An abstract "lets readers get the gist or essence of the paper quickly, in order to decide whether to read the full paper" -- I don't think we should do that by summarizing the documents contents. We should achieve that by clearly articulating the vision of the technology... what does the world look like now, and how does this specification improve upon the state of the world.

We're trying to say: "This technology enables people to take their physical credentials into the online world but with better security and utility than traditional physical credentials." ... without diving down into the details. If people read just that first paragraph, they should get a good idea of what the technology is about.

[TallTed]

I do not think that the existing "Abstract" is an abstract, and I would rather see no titular "Abstract" than have it be persisted here as such, especially given that its text is also found in toto as the first paragraph of the "Introduction".

I can see no justification for using the same paragraph both as the document's "Abstract" and as the first paragraph of the "Introduction". I have found no example of similar in any other W3 spec (and if such surfaces, I would strongly advise that WG or its successor to change it).

An abstract ("a short form of a speech, article, book, etc., giving only the most important facts or ideas") has a different purpose than an introduction ("a short speech or piece of writing that comes before a longer speech or written text, usually giving basic information about what is to follow").

In my experience of Abstracts in other fields, and even in this field outside of W3C specifications, they generally assume that their readers are more than passingly familiar with the subject matter. Perhaps this is because they are largely found in academic papers that are destined for a conference of subject matter experts.

I will readily grant that my suggested abstraction is imperfect. I said when I first suggested it that I used ChatGPT to produce the start of it, though I did make some edits to what ChatGPT provided (which I regrettably did not preserve in its original form).

We're trying to say: "This technology enables people to take their physical credentials into the online world but with better security and utility than traditional physical credentials."

I think it's overly simplified, but that quoted sentence is better than the existing "Abstract", and I would not object to using a slightly adjusted version of that quoted sentence instead of my big paragraph:

The technology specified herein enables people to take analogs of their traditional physical credentials into the online world, while providing better security and utility in the new online credentials than may be found in the old.

[msporny]

@TallTed wrote:

I can see no justification for using the same paragraph both as the document's "Abstract" and as the first paragraph of the "Introduction".

I agree, so can we change the introduction to something else?

they generally assume that their readers are more than passingly familiar with the subject matter. Perhaps this is because they are largely found in academic papers that are destined for a conference of subject matter experts.

Yes, and I find this approach in academic literature quite obtuse (and lazy) and is one of the reasons why many scientists struggle with conveying why their ideas are important to the world. This is a global standard, that's open to the public. The public, presuming a minimum of a high-school level of education, should be able to read our Abstract and understand what the document is about. I'd go a bit further and argue that they should be able to read just about everything in the Introduction and get a good idea of what this ecosystem is about and how we achieve what we achieve (and we're increasingly failing to do this in the specification, IMHO).

The technology specified herein enables people to take analogs of their traditional physical credentials into the online world, while providing better security and utility in the new online credentials than may be found in the old.

^ Yes, but that's what the current Abstract text is basically saying, isn't it... only, in a way that is better than the text above (which is an improvement, in some areas, and not in others -- it's too vague, IMHO).

I'd like to see more opinions on what we should try to do here. I think we need more than a sentence, but less than what's been proposed. Three to four sentences feels adequate (which is kinda-sorta what we have now), with some word smithing.

[wip-abramson]

I tend to agree with @msporny on this.

I think the current abstract is okay, but there is room for some minor wordsmithing.

I agree with @TallTed that the abstract should not be repeated in the introduction. So we should remove that text from the introduction and propose some new text there that introduces the sections and content of the specification. I think @TallTed the paragraph you propose in this PR is in that direction.

[brentzundel]

minor nit, otherwise LGTM