Improve and consider moving definitions

[nicholascar]

This issue was created in the Profile Guidance document and is listed in it. Once consensus on addressing it is reached here in comments below, the results will be added to the document and the issue closed.

(Antoine:) As part of re-structuring effort I've pasted Nick's original definitions in an appendix. In Oct 2018 there has been some back-and-forth and we agreed that the definition of profile should be in the introduction, while the others can stay in an appendix.
In any case we should keep them somewhere for now, even if they obviously need to be polished. It's good to have a reference set of terms we've been interested in at some point. I think we should welcome input from the WG, on whether we should add other terms here. For example, 'schema', as referred at #242 (comment)

[aisaac]

Solutions to this issue should also address @agreiner 's concerns in #418

[nicholascar]

From now closed #373: Extend the second paragraph of 'profile' to indicate data use, not just metadata

[kcoyle]

Definitions have been moved. Should we close this and open another for the content of the definitions? The current ones could be pasted into an issue and we would work on the definitions there.

[nicholascar]

Yes, that seems like a good idea, please close

[kcoyle]

@aisaac I'll wait to hear from you on whether to close the issue on moving definitions and how we should work with the definitions themselves.

[aisaac]

@kcoyle thanks for the notice. I am unpiling the notes from the last 4 days so may miss the context of the discussion. And may revise what I'm writing here...

But for the moment I still stand with the position I've expressed at #242 (comment) and which used to be in the document (apparently it was removed this week-end). There I had suggested to put the definitions as appendix, so that they don't make reader focus on them first. We can still hyperlink a definition from the first occurrence of the notion in the text or use tooltip to show them.

[kcoyle]

@aisaac I've looked at a handful of W3C recommendations (linked from the home page) and most of them cover "important terms" or "definitions" early on in the document. The manual of style doesn't mention term definitions. I suggested putting them early in the document just based on what I saw in other documents. I think the key thing is that they are linked in the text.

[aisaac]

@kcoyle ok we shall try to retain a linking, then!

I understand that definitions at first look good, especially in other specs. In the case of our definitions (at least the ones we have now) we could just keep the profile one in the intro.
My point in #242 is that the others (formalism, standard, specification) are going to require a lot of time to discuss.
Besides, they will look controversial anyway and be a not so crucial distraction to the reader - as putting definitions first usually hints that the reader should accept them, which is not so crucial for our own doc I believe. I mean, I believe that the document can be read by people who will have their own interpretation of 'specification', not the Oxford Dictionary one. One can read the main 'profile' definition and make it work with a handful of different definitions for the notions in that (specification, standard...) And in fact I do want this: we should be readable to a a broad audience, and not lose readers because of details like what is a specification and what is not.

[kcoyle]

@aisaac I agree. It isn't yet clear to me that we need to define things like "formalism" - maybe it would be better to use words that are less ambiguous.

So let's begin with having "profile" defined early on as part of our introduction, and drop the rest to the bottom of the document to be scrutinized when we get further along. Does that sound ok?

[aisaac]

@kcoyle ok I can work this this evening.
@nicholascar @rob-metalinkage any objection?

[nicholascar]

No objections from me. Makes sense that "profile" is our up front main definition and then others taht we need are perhaps demoted as being secondary.

[aisaac]

OK PR #484 is up for you to approve! And I'm changing the description of this issue so that what's included in the guidance doc makes a bit more sense.

[nicholascar]

Closing