Subject: [clue] framework references to other documents - normative or informative?

From: "Duckworth, Mark" <[email-masked]>
Date: Wed, 16 Jul 2014 10:20:39 -0700

draft-ietf-clue-framework-16 has a section for "Informative References", with a note reminding us to check if any of these should be normative.  By what criteria do we decide if a reference is informative or normative?  Can anybody suggest how these should be categorized?

And it seems to me we should add references to the other CLUE documents like data model, protocol, signaling, and I would think those would be normative, is that right?

Mark

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 16 Jul 2014 13:38:29 -0400

On 7/16/14 1:20 PM, Duckworth, Mark wrote:
> draft-ietf-clue-framework-16 has a section for “Informative References”,
> with a note reminding us to check if any of these should be normative.
> By what criteria do we decide if a reference is informative or
> normative?  Can anybody suggest how these should be categorized?

See RFC3967

> And it seems to me we should add references to the other CLUE documents
> like data model, protocol, signaling, and I would think those would be
> normative, is that right?

If the references aren't required to read the framework document itself 
then there is no need to include the reference. In fact IdNits will 
complain if you include references that aren't used at all in the doc.

The complete set of normative references can be obtained by recursion.

But perhaps a case can be made that an overview might be written to help 
the reader understand the document set, and that would include 
references to all the documents.

	Thanks,
	Paul

---

From: "Duckworth, Mark" <[email-masked]>
Date: Wed, 16 Jul 2014 10:59:54 -0700

Thanks, I'll look at RFC3967.

> the reader understand the document set, and that would include references
> to all the documents.

Yes, that's what I meant.  Do you think the framework should include such an overview?

Mark

> -----Original Message-----
> From: clue [mailto:[email-masked]] On Behalf Of Paul Kyzivat
> Sent: Wednesday, July 16, 2014 1:38 PM
> To: [email-masked]
> Subject: Re: [clue] framework references to other documents - normative or
> informative?
> 
> > draft-ietf-clue-framework-16 has a section for "Informative
> > References", with a note reminding us to check if any of these should be
> normative.
> > And it seems to me we should add references to the other CLUE
> > documents like data model, protocol, signaling, and I would think
> > those would be normative, is that right?
> 
> then there is no need to include the reference. In fact IdNits will complain if
> you include references that aren't used at all in the doc.
> 
> the reader understand the document set, and that would include references
> to all the documents.
> 
> 	Thanks,
> 	Paul
> 
> _______________________________________________
> clue mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/clue

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 16 Jul 2014 14:23:21 -0400

> Yes, that's what I meant.  Do you think the framework should include such an overview?

Judgement call.

In my personal opinion it isn't needed - just makes the doc bigger. 
Working top down will lead to the documents when they are needed.

YMMV.

	Thanks,
	Paul

---

From: Mary Barnes <[email-masked]>
Date: Wed, 16 Jul 2014 13:42:55 -0500

I would think in cases where the framework currently refers explicitly to
other WG deliverables, we could add a reference.  I don't think it's
absolutely necessary to add an overview to the framework.

As far as the other references RFC 2119 and all the others could be made
normative, although it's easier to leave the informational docs as
Informative for obvious reasons (i.e., no downrefs).

Mary.

On Wed, Jul 16, 2014 at 12:59 PM, Duckworth, Mark <
[email-masked]> wrote:

> complain if

---

From: "DRAGE, Keith (Keith)" <[email-masked]>
Date: Wed, 16 Jul 2014 22:02:28 +0000

I strongly recommend keeping any referencing to the minimum you need - this is not an academic paper for which you get kudos for the length of the reference list.

So normative references - those where you actually need the text from the referenced document to implement the text in your document with RFC 2119 language. Follow the rules in RFC 3967. [Remember that if you ever get to identifying any conformant implementations, e.g. for standards track, the normative references need to be assessed as much as any RFC 2119 language in you document.] So treat the assessment of the need any normative references in the same way as you would consider the need for writing a MUST, a  SHOULD or a MAY.

Informative references. Concentrate on those you really need to give understanding of any key concepts, or explain any terminology.

Leave the problem of an overview document to someone else.

Keith

> From: clue [mailto:[email-masked]] On Behalf Of Duckworth, Mark
> Sent: 16 July 2014 19:00
> To: Paul Kyzivat; [email-masked]
> Subject: Re: [clue] framework references to other documents - 
> normative or informative?
> 
> > But perhaps a case can be made that an overview might be written to 
> > help the reader understand the document set, and that would include 
> > Subject: Re: [clue] framework references to other documents - 
> > normative or informative?
> > 
> > If the references aren't required to read the framework document 
> > itself then there is no need to include the reference. In 
> fact IdNits 
> > will complain if you include references that aren't used at 
> all in the doc.
> > 
> > But perhaps a case can be made that an overview might be written to 
> > help the reader understand the document set, and that would include

---

From: "Duckworth, Mark" <[email-masked]>
Date: Wed, 16 Jul 2014 15:11:58 -0700

Thanks Keith, that sounds like good advice!
Mark

> From: DRAGE, Keith (Keith) [mailto:[email-masked]]
> Sent: Wednesday, July 16, 2014 6:02 PM
> To: Duckworth, Mark; Paul Kyzivat; [email-masked]
> Subject: RE: [clue] framework references to other documents - normative or
> informative?
> 
> I strongly recommend keeping any referencing to the minimum you need -
> this is not an academic paper for which you get kudos for the length of the
> reference list.
> 
> So normative references - those where you actually need the text from the
> referenced document to implement the text in your document with RFC
> 2119 language. Follow the rules in RFC 3967. [Remember that if you ever get
> to identifying any conformant implementations, e.g. for standards track, the
> normative references need to be assessed as much as any RFC 2119 language
> in you document.] So treat the assessment of the need any normative
> references in the same way as you would consider the need for writing a
> MUST, a  SHOULD or a MAY.
> 
> Informative references. Concentrate on those you really need to give
> understanding of any key concepts, or explain any terminology.
>