Subject: Use cases in a standards track document.

From: Christian Hopps <[email-masked]>
Date: Thu, 03 Dec 2015 12:02:43 -0500

Hi Folks,

I have a standards track document (draft-ietf-isis-node-admin-tag) 
that has an Application (use cases) section. To my thinking this 
section should be an Appendix to make very clear that the document 
is not standardizing the use cases. The text they have at the 
start of this section is:

"  This section lists several examples of how implementations 
might use 
   the Per-node administrative tags.  These examples are given 
   only to demonstrate generic usefulness of the router tagging 
   mechanism.  An implementation supporting this specification is 
   not required to implement any of the use cases.  It is also 
   worth noting that in some described use cases routers 
   configured to advertise tags help other routers in their 
   calculations but do not themselves implement the same 
   functionality."

Which is a bit klunky as well.

Is there any precedent (or guidance) on including non-normative 
use cases in a standards track document? 

Thanks,
Chris.

---

From: Justin Richer <[email-masked]>
Date: Thu, 3 Dec 2015 12:34:34 -0500

Chris,

It happens all the time, and it can often be useful to enumerate some concrete use cases. I’ve found it’s generally useful to keep fully fledged use cases in an appendix, and to explicitly introduce them as non-normative. For example, with your text below, start instead with:

   This section lists several non-normative examples of how implementations…

I also prefer smaller, more diverse examples throughout the document to showcase different points and options in practice.

 — Justin

> On Dec 3, 2015, at 12:02 PM, Christian Hopps <[email-masked]> wrote:
> 
> Hi Folks,
> 
> I have a standards track document (draft-ietf-isis-node-admin-tag) that has an Application (use cases) section. To my thinking this section should be an Appendix to make very clear that the document is not standardizing the use cases. The text they have at the start of this section is:
> 
> "  This section lists several examples of how implementations might use   the Per-node administrative tags.  These examples are given   only to demonstrate generic usefulness of the router tagging   mechanism.  An implementation supporting this specification is   not required to implement any of the use cases.  It is also   worth noting that in some described use cases routers   configured to advertise tags help other routers in their   calculations but do not themselves implement the same   functionality."
> 
> Is there any precedent (or guidance) on including non-normative use cases in a standards track document?
> Thanks,
> Chris.

---

From: Paul Kyzivat <[email-masked]>
Date: Thu, 3 Dec 2015 12:54:24 -0500

> I also prefer smaller, more diverse examples throughout the document to showcase different points and options in practice.

I think this is a matter of taste and may very based on circumstances 
and how important the use cases are to the document. (SIP has several 
documents that contain *only* use cases. Of course those aren't normative.)

It can be helpful to get the use cases out of the main document flow. 
But in other cases it is important for the document to start with use 
cases, and for the reader to have seen them, before getting into the 
normative content. So in that case an appendix may not be appropriate.

As long as the section is clear that it isn't normative, and it has no 
2119 keywords, there should be no confusion.

	Thanks,
	Paul

---

From: Christian Hopps <[email-masked]>
Date: Thu, 03 Dec 2015 13:06:07 -0500

Justin Richer <[email-masked]> writes:

> Chris,
>
> It happens all the time, and it can often be useful to enumerate 
> some concrete use cases. I’ve found it’s generally useful to 
> keep fully fledged use cases in an appendix, and to explicitly 
> introduce them as non-normative. For example, with your text 
> below, start instead with:
>
> I also prefer smaller, more diverse examples throughout the 
> document to showcase different points and options in practice. 
 
Yeah in talking off-thread about this, I think my reaction comes 
From the fact that there's more use-case (full-fledged) text than 
actual normative text, i.e., it dominates the document, and 
distracts from the simplicity of the protocol changes. Relegating 
the use-cases to an Appendix would tend to obviate that I think.

Thanks,
Chris.

>> I have a standards track document 
>> (draft-ietf-isis-node-admin-tag) that has an Application (use 
>> cases) section. To my thinking this section should be an 
>> Appendix to make very clear that the document is not 
>> standardizing the use cases. The text they have at the start of 
>> this section is:
>> 
>> might use   the Per-node administrative tags.  These examples 
>> are given   only to demonstrate generic usefulness of the 
>> router tagging   mechanism.  An implementation supporting this 
>> specification is   not required to implement any of the use 
>> cases.  It is also   worth noting that in some described use 
>> cases routers   configured to advertise tags help other routers 
>> in their   calculations but do not themselves implement the 
>> same   functionality."
>> 
>> use cases in a standards track document?  Thanks, Chris.

---

From: "DRAGE, Keith (Keith)" <[email-masked]>
Date: Thu, 3 Dec 2015 20:44:09 +0000

I don't think appendixes are automatically informative, so if you use that, you will still need to make clear that the contents are informative. An appendix could well be used to document an optional extension to the main document, for example.

Sometimes you also need the informative material to introduce the normative contents, so such an approach would not work in this case. For example, I suspect that the majority of standards track RFCs have no normative content in the section immediately after the abstract (ignoring other proforma sections); rather this is used for introductory material.

In conclusion, adopt any format you like that allows you to present the information clearly, but also allows the normative material to be easily found and identified. A structure where a normative requirement can be lost because it is buried in an otherwise informative section or whatever should be avoided; such a loss could lead to non-conformant material being on the market through no desire of the implementor.

Regards

Keith

-----Original Message-----
From: WGChairs [mailto:[email-masked]] On Behalf Of Christian Hopps
Sent: 03 December 2015 18:06
To: Justin Richer
Cc: [email-masked]
Subject: Re: Use cases in a standards track document.

Justin Richer <[email-masked]> writes:

> Chris,
>
> It happens all the time, and it can often be useful to enumerate some 
> concrete use cases. I’ve found it’s generally useful to keep fully 
> fledged use cases in an appendix, and to explicitly introduce them as 
> non-normative. For example, with your text below, start instead with:
>
> I also prefer smaller, more diverse examples throughout the document 
> to showcase different points and options in practice.
 
Yeah in talking off-thread about this, I think my reaction comes From the fact that there's more use-case (full-fledged) text than actual normative text, i.e., it dominates the document, and distracts from the simplicity of the protocol changes. Relegating the use-cases to an Appendix would tend to obviate that I think.

Thanks,
Chris.

>> cases) section. To my thinking this section should be an Appendix to 
>> make very clear that the document is not standardizing the use cases. 
>> The text they have at the start of this section is:
>> 
>> Is there any precedent (or guidance) on including non-normative use 
>> cases in a standards track document?  Thanks, Chris.

---

From: Toerless Eckert <[email-masked]>
Date: Thu, 3 Dec 2015 15:06:25 -0800

My suggestions (partially tongue in cheek):

Don't let anybody talk you out of writing as much explanations and examples
as you see fit. IETF work product do on average suffer from being too terse
and undecipherable especially the more difficult a standard gets because
authors like to give up on anything optional to cut the work. It is good though
to build up any optional text based on actual participant questions to
have some proof that its useful (instead of just explaining lots of
background nobody but you finds interesting).

If optional/non-normative text outweights the normative text, it may be useful
to consider splitting it out into a separate (informational) RFC. This is easier
to justify if it seems likely that other documents may want to reference the use-case
document without even necessarily referencing the standard part. Or just because you
want to work on your your h-index (http://www.arkko.com/tools/allstats/c_chopps.html).

Cheers
    Toerless

On Thu, Dec 03, 2015 at 12:54:24PM -0500, Paul Kyzivat wrote:
> >concrete use cases. I???ve found it???s generally useful to keep fully 
> >    This section lists several non-normative examples of how 
> >    implementations???
> >
> >I also prefer smaller, more diverse examples throughout the document to 
> >showcase different points and options in practice.
> 
> >  ??? Justin
> >>I have a standards track document (draft-ietf-isis-node-admin-tag) that 
> >>has an Application (use cases) section. To my thinking this section 
> >>should be an Appendix to make very clear that the document is not 
> >>standardizing the use cases. The text they have at the start of this 
> >>section is:
> >>
> >>"  This section lists several examples of how implementations might use   
> >>the Per-node administrative tags.  These examples are given   only to 
> >>demonstrate generic usefulness of the router tagging   mechanism.  An 
> >>implementation supporting this specification is   not required to 
> >>implement any of the use cases.  It is also   worth noting that in some 
> >>described use cases routers   configured to advertise tags help other 
> >>routers in their   calculations but do not themselves implement the same  
> >>functionality."
> >>

-- 
---
Toerless Eckert, [email-masked]