Subject: Re: [apps-discuss] Terry Manderson's Discuss on draft-ietf-appsawg-text-markdown-use-cases-02: (with DISCUSS)

From: Barry Leiba <[email-masked]>
Date: Wed, 8 Jul 2015 08:30:45 -0400

>
> This does not strike me as a 'use cases' document when you make IANA
> requests to register identifiers with IANA. These seem more appropriate
> in draft-ietf-appsawg-text-markdown-08.
>

I'm not sure why you think this is a problem -- maybe you can ekaborate --
but the working group thought it best to split this up, defining the media
type and registry in one doc, and describing the variants and making the
registrations in another.

Barry

---

From: "Terry Manderson" <[email-masked]>
Date: Tue, 07 Jul 2015 20:31:29 -0700

Terry Manderson has entered the following ballot position for
draft-ietf-appsawg-text-markdown-use-cases-02: Discuss

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.

The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-appsawg-text-markdown-use-cases/

----------------------------------------------------------------------
DISCUSS:
----------------------------------------------------------------------

---

From: Terry Manderson <[email-masked]>
Date: Thu, 9 Jul 2015 00:47:44 +0000

Hi Barry,

This is a fairly simple problem to fix.

My anxiety was cased by the incorrect targeting of the document as a use
cases. It isn't. Lets call it what it is.
If it was to be a use case document. I think Murray has already proposed
to work with the authors on this and when I see that response I can clear
the discuss.

As a side: normally I would say put the registrations with the prime
document, however as you say, the working group chose to split the
document and that is fine.

Cheers
Terry

On 8/07/2015 10:30 pm, "Barry Leiba" <[email-masked]> wrote:

>I'm not sure why you think this is a problem -- maybe you can ekaborate
>-- but the working group thought it best to split this up, defining the
>media type and registry in one doc, and describing the variants and
>making the registrations in another.
>
>
>Barry
>

---

From: Sean Leonard <[email-masked]>
Date: Fri, 10 Jul 2015 20:25:45 -0700

Yes: the working group chose to split the document along those subject matter lines.

When I wrote the draft, I called it “use-cases” because it was as pithy a way as any to summarize and condense the subject matter, namely (quoting from the abstract):
Background information,
local storage strategies, and
additional syntax registrations [with examples]

To my mind “use cases” meant: here are all of these really interesting use cases for Markdown (including “cases where Markdown is in use”), either that motivated its creation, or that have cropped up since its creation. Local storage strategies would be an example of a case where Markdown is in use in a broader system, and needs to be labeled in some systematic way.

I suppose we could call it “Markdown in Action” or “The Many Uses of Markdown” but those are a bit overwrought IMO.

Sean

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Fri, 10 Jul 2015 22:36:34 -0700

How about "Registration of Markdown Variants"?

On Fri, Jul 10, 2015 at 8:25 PM, Sean Leonard <[email-masked]> wrote:

> When I wrote the draft, I called it “use-cases” because it was as pithy a
> way as any to summarize and condense the subject matter, namely (quoting
> from the abstract):
> Background information,
> To my mind “use cases” meant: here are all of these really interesting use
> cases for Markdown (including “cases where Markdown is in use”), either
> that motivated its creation, or that have cropped up since its creation.
> Local storage strategies would be an example of a case where Markdown is in
> use in a broader system, and needs to be labeled in some systematic way.
>
> I suppose we could call it “Markdown in Action” or “The Many Uses of
> Markdown” but those are a bit overwrought IMO.
>
> Sean
>

---

From: Dave Crocker <[email-masked]>
Date: Sat, 11 Jul 2015 06:32:14 -0700

> How about "Registration of Markdown Variants"?

This might be overly fussy, but I suggest:

   Registration of Text Markdown Variants

Markup is a term used for all sorts of data.  Even though "markdown" is
more distinctive than "markup" the explicit qualifier was avoid any
other possible uses of markdown for other types of data.

d/
-- 
Dave Crocker
Brandenburg InternetWorking
bbiw.net

---

From: Sean Leonard <[email-masked]>
Date: Sat, 11 Jul 2015 13:47:51 -0700

> other possible uses of markdown for other types of data.

I am pretty sure that “Markdown” (capitalized) is pretty commonly understood as this technology area, and not lightweight markup languages in general. Of course, being in a title, the true capitalization state is ambiguous. Therefore I would say -1 to that, and +1 to Registration of Markdown Variants.

However I must also say -1 to Registration of Markdown Variants because the document does a lot more than the registration of certain variants. First of all “Registration of Markdown Variants” can be interpreted to refer to the *process* of how to register variants, which is covered by the text-markdown draft (Section 6 IANA Considerations). Really it should be “Registrations of Markdown Variants” since we are talking about several specific registrations (plural noun). But even then, we are not registering all known Markdown variants, just those that are interesting enough to warrant further comment as guidance for other people who want to register other variants. So, it is more like “Registrations of Certain Exemplary Markdown Variants”.

I still think “text/markdown Use Cases” is not so bad...

Sean

---

From: Barry Leiba <[email-masked]>
Date: Sat, 11 Jul 2015 18:06:57 -0400

> However I must also say -1 to Registration of Markdown Variants
> because the document does a lot more than the registration of certain
> variants.

Yeh, I don't think it does, unless you want to say "Description and
Registration ...".  And if you want to explain in the Abstract and
Introduction what else you're aiming at, that's fine.

> First of all “Registration of Markdown Variants” can be
> interpreted to refer to the *process* of how to register variants

Really, I can't imagine that anyone would read it that way.

> Really it should be “Registrations of Markdown
> Variants” since we are talking about several specific registrations
> (plural noun).

Yes, or "Registration", collective noun; using the plural reads oddly
to me.  And I don't see that either one eliminates the possible (but,
I think, unlikely) confusion you state above.

> But even then, we are not registering all known Markdown variants

So?  I don't think anyone would expect that we are.  I don't think that matters.

> So, it is more like “Registrations of Certain
> Exemplary Markdown Variants”.

I don't think I'd say "Exemplary"; I might say "Registration of Some
Markdown Variants", perhaps.  But if you want to go in this direction,
I have no objection.

> I still think “text/markdown Use Cases” is not so bad...

You're quite in the rough on this, I think; we have several comments
about "use cases" being the wrong title, and I agree with them (though
I wouldn't have worried about it).  I do think we need to change it.

Barry

---

From: Barry Leiba <[email-masked]>
Date: Tue, 14 Jul 2015 11:15:48 -0400

> "Guidance" is a good term to use.
>
> Guidance on Markdown:
> Design Philosophies, Preservation Strategies, and Select Registrations

That seems reasonable, with a question: What does "preservation
strategies" mean?

Barry

---

From: Sean Leonard <[email-masked]>
Date: Tue, 14 Jul 2015 08:36:48 -0700

> That seems reasonable, with a question: What does "preservation

It means "how to preserve the text/markdown Content-Type along with its 
parameters outside of MIME bodies",
or, "how to preserve the author's intent when the author wrote the 
Markdown content in a certain way, so that recipients know what kind of 
Markdown (variant) the content actually is, along with the charset".

(Covered in Section 2.)

Sean

---

From: Barry Leiba <[email-masked]>
Date: Tue, 14 Jul 2015 11:53:54 -0400

> or, "how to preserve the author's intent when the author wrote the Markdown
> content in a certain way, so that recipients know what kind of Markdown
> (variant) the content actually is, along with the charset".
>
> (Covered in Section 2.)

Yes; I'm questioning whether anyone reading the title will have any
idea what "preservation strategies" means.  What's the point of
putting words into the title that don't add to (and actually detract
from) the understanding of what the title means?

Barry

---

From: John C Klensin <[email-masked]>
Date: Tue, 14 Jul 2015 12:06:32 -0400

--On Tuesday, July 14, 2015 11:53 -0400 Barry Leiba
<[email-masked]> wrote:

>>> That seems reasonable, with a question: What does
>>> "preservation strategies" mean?
>> 
>> It means "how to preserve the text/markdown Content-Type
>> along with its parameters outside of MIME bodies",
>> or, "how to preserve the author's intent when the author
>> wrote the Markdown content in a certain way, so that
>> recipients know what kind of Markdown (variant) the content
>> actually is, along with the charset".
>> 
>> (Covered in Section 2.)
> 
> Yes; I'm questioning whether anyone reading the title will
> have any idea what "preservation strategies" means.  What's
> the point of putting words into the title that don't add to
> (and actually detract from) the understanding of what the
> title means?

Barry and Sean, short of just dropping that clause, how about
"stability strategies" or "interoperability strategies"?  Both
terms are well-known in the community and give much more of a
clue as to what is being discussed than "preservation".  The use
of either in this context is a bit unusual, but it seems to me
that preserving interoperability and original intent as Markdown
documents move through systems is precisely what Sean is talking
about.

    john

---

From: Sean Leonard <[email-masked]>
Date: Tue, 14 Jul 2015 11:33:56 -0700

> documents move through systems is precisely what Sean is talking

OK.

Guidance on Markdown:
Design Philosophies, Stability Strategies, and Select Registrations

-Sean

---

From: Dave Crocker <[email-masked]>
Date: Mon, 13 Jul 2015 14:33:56 -0700

> Introduction what else you're aiming at, that's fine.

I looked a little more at the draft.  "Use cases" is simply wrong.  I
think "registration" is too narrow and maybe misleading.

My current best guess:

   Guidance on Developing and Registering Text Markdown Variants

d/

---

From: Sean Leonard <[email-masked]>
Date: Tue, 14 Jul 2015 06:47:41 -0700

Guidance on Markdown:

-Sean

---

From: Dave Crocker <[email-masked]>
Date: Tue, 14 Jul 2015 22:06:33 -0700

> from) the understanding of what the title means?

They won't.  The title language being considered now is frankly
overblown, in my view.

I think I understand the appeal of that language but it is mostly the
kind of appeal that works well for an author and poorly for a reader.

Unless I really didn't understand what I was reading, this is a document
that says something along the lines of:

     "Here are some basic styles of markdown types and the templates for
registering for them.  You might have a markdown similar to one of
these, in which case you can (easily) adapt the existing one and get
yours registered (easily) too."

This sort of document can provide very useful guidance for the next
author trying to specify and register a new markdown type.

But really, this is merely guidance for specifying and registering
(some) text markdown media-types.  Please keep the title simple and
direct and concrete, so readers will understand how the document might
help them.

d/

---

From: Terry Manderson <[email-masked]>
Date: Wed, 15 Jul 2015 19:40:54 +0000

>They won't.  The title language being considered now is frankly

[..]

I have to be frank here, I expected this to be a _very simple_ DISCUSS and
easy to clear as it's about the document's use being 'clear and accurate
for the reader'. That is all.

>direct and concrete, so readers will understand how the document might

Indeed.

I'll leave consensus on the title/description in Barry's and Murray's
hands and clear my DISCUSS.

Cheers
Terry